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This publication supports Data Facility Product, a component of 
MVS/Extended Architecture (MVS/XA), and provides application 
programmers with the information necessary to use the linkage 
editor and loader to prepare the output of a language translator 
for execution. Additional information on the operation and use 
of the linkage editor and loader is directed to the system 
programmer responsible for installing and maintaining the 
operating system. 


This publication contains an introduction and two major parts: 





"Introduction" defines the functions and gives 
Peco emeoce ners for the use of the linkage editor and 
oader. 


"Part I. Linkage Editor" describes the Processing facilities 
and operation of the linkage editor: 


"Chapter 1. Overview" describes object and load modules 
and gives a general overview of linkage editor 
processing. 


"Chapter 2. Uses of the Linkage Editor" provides 
descriptions of the functions of the linkage editor, and 
explains its relationship to the operating system. 


"Chapter 3. Defining Input to the Linkage Editor" 
describes how to define the primary input data set, how 
to use the automatic library call mechanism, and how to 
include other data sets as input. 


"Chapter 4. Specifying JCL to Run a Linkage Editor Job" 
explains the job control language necessary to run a 
linkage editor job step. 


"Chapter 5. Specifying an Operation with Control 
Statements" summarizes the various linkage editor 
control statements that can be used in running the job. 


"Chapter 6. Editing a Control Section" describes how to 
change external symbols, replace control sections, 
delete control sections or entry names, order control 
sections or named common areas, and align control 
sections or named common areas on page boundaries. 


"Chapter 7. Invoking the Linkage Editor™ gives the macro 
instructions used by ‘a problem program to invoke the 
linkage editor. . 


"Chapter 8. Interpreting Linkage Editor Output" 
describes how to interpret the output load modules and 
diagnostic information produced by the linkage editor. 


"Appendix A. Sample Linkage Editor Program™ contains 
ye sample programs illustrating the use of the linkage 
editor. 


"Appendix B. Linkage Editor Requirements and Capacities" 
describes the record-processing capacities of the 
linkage editor, the types of devices that can be used 
for the intermediate data set, and the amount of virtual 
storage the linkage editor requires. 


"Appendix C. Designing and Specifying Overlay Programs" 
describes how to use the overlay facilities of the 
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linkage editor to minimize the amount of virtual storage 
required. 


e "Part II. Loader" includes function descriptions and 
operating instructions for the loader program: 


"Chapter 9. Overview and Uses of the Loader" describes 


the functional characteristics of the loader, its 
compatibility with the linkage editor, and the 
restrictions on its use. 


"Chapter 10. Preparing Input for the Loader" explains 
how to prepare an input deck for the loader, including 
how to specify EXEC statements and how to use DD 
statements to define loaded program data. 


"Chapter 11. Invoking the Loader™ shows how to use the 
EXEC statement or specified macro instructions to invoke 
the loader program. 


"Chapter 12. Interpreting Loader Output™ describes how 
to interpret the diagnostic and error messages, and the 
optional storage map, produced by the loader program. 


"Appendix D. Loader Storage Considerations" describes 
the virtual storage space required by the loader 
program. 


"Appendix E. Loader Return Codes" lists the return codes 
that can result from loader processing and defines their 
meanings. 


The diagnostic messages issued by both the linkage editor and 
the loader progres are described in 


MV57Extended Architecture 
» Volumes 1 and 2, GC28-1376 and 


GC28-1377. the’ description of each message includes an 
ene pee eens a system action, and a problem determination action 
o be taken. 
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In order to use this book efficiently, you should be familiar 
with MVS/Extended Architecture job control language. 


REQUIRED PUBLICATIONS 


You should be familiar with the information presented in the 
following publications: 


A 


describes the job control 


language used to run the linkage editor and loader programs. 


se Lad 
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M 260. Ff 5a Lora $ tem Message 
describes the diagnostic messages issued by the linkage 


editor and loader programs. 


RELATED PUBLICATIONS 


Within the text, references are made to the publications listed 
in the table below: 


iv MVS/XA Linkage Editor and Loader User's Guide 








Short Title Publication Title Order Number 
(as it appears 
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Data MVS/7Extended Architecture 


Administration Data Administration Guide 
Guide 


Data MVS/Extended Architecture LYB8-1195 
Areas——JES3 Data Areas-——JES3 


Initialization MVS/Extended Architecture 6GC28-1149 
System Programming Library: 
Initialization and Tuning 


MVS/Extended Architecture GC28-1148 
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Linkage Editor MVS/7Extended Architecture LY26-3902 
Logic Linkage Editor Logic 
Loader Logic MVS/Extended Architecture LY26-3901 
Loader Logic 


Routing and MVS7Extended Architecture 


Descriptor Message Library: Routing 
Codes and Descriptor Codes 


MVS/Extended Architecture 


System Programming Library: 
Service Aids 













and Tuning 




















Service Aids G6C28-1159 










SMP System OS/VS_ System Modification 6028-0673 


Programmer's Program (SMP) System 
Guide Programmer's Guide 
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Guide 
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GC26-4009 
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Reference 
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Reference(OS/VS2 TSO 
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as updated by Supplement | 
$D23-0259 for MVS/XA) 
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supplement, LDB3-2078) 
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Data Administration: 
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TSO Command 
Language 
Reference 








TSO/VE Data 
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Utilities GC26-4018 
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NOTATIONAL CONVENTIONS 


A uniform system of notation describes the format of linkage 


vi 


editor and loader control statements. 


of the language; it simply provides a basis for describing the 


structure of the commands. The command format illustrations in 


this book use the following conventions: 


e Brackets [£ ] indicate an optional parameter. 


e Braces { } indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 


Items separated by a vertical bar (]) represent alternative 


items. No more than one of these items may be selected. 


e An ellipsis (...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. | 


® Other punctuation Cparentheses, commas, spaces, etc.) must 
be entered as shown. A space is indicated by a blank. 


e BOLDFACE type indicates the exact characters to be entered, 
except as described in the first four bullets. Such items 
must be entered exactly as illustrated. 


e Lowercase underscored type specifies fields to be supplied 


by the user. 


e BOLDFACE UNDERSCORED type indicates a default option. If 


the parameter is omitted, 
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the underscored value is assumed. 








This notation is not part 





| SUMMARY OF CHANGES 





| RELEASE 1.2 LIBRARY UPDATE,» JANUARY 1987 


| SERVICE CHANGES 
Information has been added, corrected, or deleted to reflect 
technical service changes. 


RELEASE 1.22 FEBRUARY 1984 


REVISION AND RESTRUCTURE 


The contents of this manual are substantially the same as in 
Release 1.0. Changes are as follows: 


® The manual has been restructured for ease of use. 
e References to other manuals have been updated. 
e Minor technical changes have been made in Chapter 5, 


"Specifying an Operation with Control Statements." These 
changes are indicated by revision bars. 





Summary of Changes vii 











fess 


fle 


fade 


MVS/XA Linkage Editor and Loader User's Guide 











Introduction e e eo e e e e e e e ® ® e e e@ e e@ e @ e e @ e 
Part I. Linkage Editor elem Re “SAAB ee Nea Hee eer ess SA te! et He). del fe 


Chapter l. Overview e e e e e @ @ e e@ e @ @ e e e @ e e 
Object and Load Modules 3 Se lg ge “gt gt cas oe ee a HS ES. . S 
External Symbol Dictionary oe 
Text : , 
Relocation Dictionary. ‘ 
End Indication F ae 
Linkage Editor Processing. 
Input and Output Sources er. ee “cae oa Ee SE a RE RS TS 
Load Module Creation he te), as la. he dpe tt GS, ae th -s tS  e G 
Assigning Addresses ; : 
Resolving External References 


Chapter 2. Uses of the pede Eaayer 65 ser ar Ser ee. ee 
Linkage Editor Input ; Be pies a tae oe, SR 
Links Modules a ‘ 
Edits Modules 
Aligns Control Sections. or Common Areas’ on Page 
Boundaries eee ES Tal ot 
Accepts Additional Input Sources 
Reserves Storage Ee ng 
Processes Pseudoregisters. 
Creates Overlay Programs ‘ 
Creates Multiple Load Modules” 
Provides Special ooraeee le and Diagnostic Output 
Options Ma} GR ae. Sa oe a 
Assigns Load Module. Attributes , 
Allocates User-Specified Virtual Storage Areas 
Stores System Status Index Information veer 
Traces Processing History 
Lengthens Control Sections or “Named Common Sections 
Assigns an Authorization Code to Output Load Modules 
Assigns Addressing Mode Pi ck St cee Se. ae. VG ee ae ee. 
Assigns Residence Mode 
AMODE/RMODE Hierarchy 
Assigns Read-only Attribute : 
Relationship to the Operating System 
Time Sharing Option (TSO) 


Chapter 3. Defining Input xe me panKage ermcaes a a 
Primary Input Data Set ; Sy ese “ee. det 
Object Modules 
From Cards ; 
As a Member of a Partitioned Data “Set. 
Passed from a Previous Job Step 
Created in a Separate Job 
Control Statements 
Object Modules and Control Statements 
Control Statements in the Input Stream 
Control Statements in a Separate Data Set 
Automatic Library Call Se Ste ee Ge oe, ae 
SYSLIB DD Statement ¢. de hy. hk 
System Call Library S oe 8 
Private Call Libraries : 
Concatenation of Call Libraries. 
Library Control Statement : 
Additional Call Libraries 
Restricted No-Call Function 
Never-Call Function : 
NCAL Option —— 

Included Data Sets a aT ae ae 
Including Sequential Data “Sets a a a 
Including Library Members é 4 
Including Concatenated Data Sets 


Contents 





BRUNIA NFOCUWUUUWUUONAR GW - 


Te eee 


1X 











Chapter 4. 


Specifying JCL to Run a ee EEeee a ‘ 


EXEC Statement—Introduction a 
EXEC Statement——Job ils Options | Be, fe *G ae 
Module Attributes ee St tah ee 
Downward Compatible Attribute BN Mee ek. Gua UB. cae 
Scatter Format Attribute See Ae te Es es a ee 
Not Editable Attribute Boece te oe, ce Ue GL ae ay fae ck; 
Only-~Loadable Attribute S'S 
Overlay Attribute wx 
Reusability Attributes 
Refreshable ee : 
Test Attribute gt en SG 
Authorization Code . ao ee. es 
Addressing Mode Attribute a ee 
Residence Mode Attribute : 
Combinations of Addressing Mode “and Residence ‘Mode 
Default Attributes ; co fey Se Be ke Al ro a a ee 
Incompatible Attributes Ye 
Special Processing Options 
Exclusive Call Option ee 2 we, a ie ee Ok 
Let Execute Option é. ey es Oe CS 
No Automatic Library-Call ‘Option , 
Space Allocation Options : 
SIZE Option a tak 
DCBS Option 
Output Options ; 
Control Statement Listing Option 
Module Map Option : 
Cross Reference Table Option : 
Alternate Output CSYSTERM) Option 
Incompatible Job Step Options 
EXEC Statement——Region Parameter 
EXEC Statement—Return Code 
DD Statements : 
Linkage Editor DD Statements 
SYSLIN DD Statement ; , 
SYSLIB DD Statement Pecks 
SYSUT1 DD Statement 
SYSPRINT DD Statement 
SYSLMOD DD Statement 
SYSTERM DD Statement 
Additional DD Statements 
Size Parameter Guidelines 
Cataloged Procedures : 
Linkage Editor Cataloged Procedures’ 
Procedure LKED ar a a ee 
Procedure LKEDG — 
Overriding Cataloged Procedures’ 
Overriding the EXEC Statement 
Overriding DD Statements 
Adding DD Statements ; 


Chapter 5. 


epect yang an eer gen re aaa arenemelne 


General Format 

Format Conventions 

Placement Information 

ALIAS Statement 

CHANGE Statement Bid --6. vals ee. As Ge SD et. os 

ENTRY Statement te IS. bt ee EE. ee GR abe a FD Ga . dee 8 
EXPAND Statement Be. ee, ee AEA ee. ae ct pee WO 
IDENTIFY Statement bo ae me ee we, Be et ce 2 
INCLUDE Statement Boar et ok. ee SH. ae a aa 
INSERT Statement Ge We SR ER ole: hs a SS A ee wer cs 
LIBRARY Statement Sos es SR Se UB a A a 
MODE Statement os ds. we eo ee ee GN eS 
NAME Statement C an & 

ORDER Statement a 

OVERLAY Statement Sh ty i Gh. en ae Gs. bo Se uee ae dee we % 
PAGE Statement i ee My ea SG ee es Se 
REPLACE Statement Se WW. as Ma a ce ; ; 
SETCODE Statement ye. Me eS ge, de OM 

SETSSI Statement i ae a See OE oe 


x MVS/XA Linkage Editor and Loader User's Guide 




















Chapter 6. Editing a Control Sector a eS ae ee ae ee ee 92 


Editing Conventions : So ws we te “as Ste Ue 8 92 
Changing External Symbols fe. «3eie we Mar -Me o SSeS Be bie Wak. Se, Se ee ee 94 
Replacing Control Sections gee Zt tse, Se ok. Se, ee ee, a ee Be et cs 95 

Automatic Replacement eM ee tes A Me len ie es eC Se 96 
Example 1] pes tee Bb. eG. ee ese ts oe a. SS 96 
Example 2 Bee Mis tes Ea tee, ee SE -g  ae  at.  g oaes  e 97 

REPLACE Statement. er ee ee ee 98 

Deleting a Control Section or Entry Name ac 3 a ae ee 100 

Ordering Control Sections or Named Common Areas’ Ja wit, Mas. Xe 102 

Aligning Control Sections or Named Common Areas on Page 
Boundaries By tke “We, Wee SR Jee SG OE EL <e e R tee e G GS 103 


Chapter 7. Invoking the Linkage Editor bo .@k sor Oy es Se He. 105 
Chapter 8. aire eres ETnkage EdZ toe ike aeds ao ee Wh, er 107 








Output Load Module : : ede: Ae Me 107 
Output Module Library Se. a Gat. “is ocak er wks tas. wD Sete cle GE as eh a: We 107 
Member Name : eter Wee Mer ies oe Ge Se aS oe, EO eae ee ee 108 
Alias Names i clea ign ied acne ioe: Je. es ae We ee ae wd ee se Oe ten 109 
Entry Point Oo oe eos ws 110 
Authorization “Code ; Ps es Sa ae es 111 
Residence and Addressing Modes a ae ee ee ee lll 
Reserving Storage in the Output Load Module: lll 
Processing Pseudoregisters a , ll2 
Multiple Load Module Processing 112 
Diagnostic Output . a ke 4 113 
Diagnostic Messages ; 113 
Module Disposition Messages 113 
Error/Warning Messages 114 
Sample Diagnostic Output 115 
Optional Output : 116 
Control Statement Listing ome GE ER 116 
Module Map ji Sak 2) he, Gee. ee- Ae e a G e 116 
Cross- Reference ‘Table. be AS: Jey va “ee Se oe, es ae oe es Se 117 
Load Module Format i ik He. St Cie Bip > cm a, a ww fa. ee. 118 
Part II. Loader @ e e @ e @ @ @ e e @ e e@ e e @ @ e e @ 121 
Chapter 9. Overview and Uses of ene eae Se Je be niet Se. ag -% 122 
Functional Characteristics i a ee ey eee ; 122 
Addressing Mode ‘ 122 
Residence Mode ; 123 
AMODE/RMODE Combinations 124 
Implied AMODE or RMODE 124 
Compatibility and Restrictions 127 
Time Sharing Option CTS0O) : ae ae ae 127 
Processing Object Modules in Virtual Storage a ae 127 
Chapter 10. Preparing znpus ae ine peaeee eis. eh 128 
Input for the Loader ; oc. SE Oe ee 128 
EXEC Statement ; ES Sey Sel. ey GR te a. ee. en ee. wet Bat ca Sa Se, Oe 128 
PARM Field Format. eae Sh Sa es, hs tee Rl a oe es vag as Ge 128 
Loader Options j , b Se elk we OH 129 
AMODE=mode: Specifying Address “Mode ee ae oe 129 
CALLINOCALL: Automatically Searching SYSLIB wt ae “Ee 129 
EP=name: Specifying the Program Entry Point be. ier 130 
LET{NOLET: Executing with Severity 2 Errors te oe 130 
MAP|NOMAP: Printing a Program Map ; eta et es 130 
NAME=name: Identifying the Loaded Program a a 130 
PRINTINOPRINT: Printing Messages on SYSLOUT a a ee 131 
RES|NORES: ee ene earcoang the Panik Pack Area 
Queue ee oe . ae fae 131 
RMODE=mode: Specifying Residence Mode Sab. eh ep Oe ds. 131 
SIZE=size: Specifying Virtual Storage a a oe ee ee 131 
TERMINOTERM: Sending merceaes - “SYSTERM a ae oe a 132 
EXEC Statement eee ae. os beh wee e+ Tbe os 132 
DD Statements So WD. te ees ee eres Rs 2k EN er Bt eee 3a, ae He 132 
SYSLIN DD Statement. Bm. Set es ae Ro es. hie He ee oe eee ec ce, 133 
SYSLIB DD Statement tte ar Me hy ca. aa te OL 134 
SYSLOUT DD Statement Me Sue Bs J “a a as, ee, Ws es. a 134 
SYSTERM DD Statement te, th ke cs dep oe. oe ay Rt. Bs. 83 os ce 134 
Loaded Program Data Sct «Vere 6d ics > Gey Suc SE aR we a, SR 135 


Contents xi 


xii 


Sample Input for the Loader Se ay ae te: ae oe es ee 
Chapter 11. Invoking The Loader ...... cece 
Chapter 12. Interpreting Loader Output ae ae ee 
Appendix A. Sample eee maa Programs i ee ee ie 


Sample Program COBFORT - 
Job Control Language gh sige nds! ew Ses ee va. DE ee 
Linkage Editor Output Be de he. cise a eg ae, Soa te Se Le 
Sample Program RPLACJOB bi See het ee ek Fs ea SS ee a CS 
ob Control Language G ter Ses. eG! See So ae 
Linkage Editor Control Statements Scie Yas se Se. Ge 
Linkage Editor Output , j. feel te ae A ke ee. 
Sample Program Sere ga: ee We te We es ae AS CE SS 
Job Control Languag ge ee Gh each See ae 
Linkage Editor Contral Statements aS ee ts 
Linkage Editor Output ‘ WE ee, Ser es, SRE Ge. 8 
Sample Program PARTDS ae “lye fos wet fer. Age oe. GY. Je CBee le em 
Job Control Language a ee ae ae ee 


Lankage Editor Control Statements. 
Linkage Editor Output a 


Appendix B. Linkage Editor pegurremencs: ane eco acer 
Capacities oa. 
Intermediate Data “Set. Ss Lobe ses ee. te Gat kes we fee. HO 


Appendix C. Designing and epecsty ng eyeneey Preerems 
Design of an Overlay Program : ; 
Single Region Overlay Program a ee ee ee 
Control Section Dependency 
Segment Dependency ‘ : 
Length of an Overlay Program 


Segment Origin BP ei ale See. coh, oe er eis V4 
Communication between. Segments So > Show Be ae des be od 
Overlay Process a en ae ee ae 
Multiple Region Overlay Program a a a a ae 
Specification of an muerney Program pence et ees 
Segment Origin - & Se else wan Ge, Ar, cos ee a A 
Region Origin Sn oe OR Bb. Cae Cae ceo RS Cee 
Positioning Control “Sections Bet, it a? yas fe ee ee a ae 
Using Object Decks : G2, ea. us 
Using INCLUDE Statements ws oe he ee Se. ee. Se 
Using INSERT Statements See geo See a RE ee, en te St 
Special Options ; ge dé GE, SS, Be So Ae a GS 
OVLY Option ee. Fe B. k> wet att See Se er. Sto wae. tee woe, SS 
LET Option gen ee en i ws Ge. Oe ee es es vs 3 es 
XCAL Option bce. SG: he Yes cid SE OR ee 


AMODE and RMODE. Options. 
Special Considerations 
Common Areas : 
Storage Requirements 


Overlay Communication Se Be ene he 
CALL Statement or CALL Macro Instruction ge 35-4 
Branch Instruction , rr a ee ae 


Segment Load CSEGLD) Macro Instruction ie tess ee wer 
Segment Wait CSEGNT) Macro Instruction S fe aoe 


Appendix D. Loader Storage Considerations ee ee 
Appendix E. Loader Return Codes Veg Me! vel Te, a? Ste. 
Glossary Pag FSS Bah ee a gs. Re. ee ae. Be ee SS te ee YS 


Index Se clas ee, “aay Ge aster. BU Wes eee. Gk Ge. GE: 1G He SE ce Se es es 


MVS/XA Linkage Editor and Loader User's Guide 


ee, 














Pant fet fend eet 


WANK OWUONN UIDW NF 


Preparing a Source Module for Execution 4 

Preparing a Source Module for Execution, and Executing the 
Load Module 

External Names and External References 6 

Use of the External Symbol Dictionary 8 

Input, Intermediate, and Output Sources for the Linkage 
Editor 10 

A Load Module Produced by the Linkage Editor 1] 
Linkage Editor Processing—Module Linkage 14 

Linkage Editor Processing~——Module Editing 15 

Linkage Editor Processing-—~Additional Input Sources 16 
System Automatic Call Libraries 28 

Processing of One INCLUDE Control Statement 

Processing of More than One INCLUDE Control cco tomsnt 33 

hal re SYSLMOD Device Types and Their Maximum Record 
izes 

abe bi Buffer Area and SYSLMOD and SYSUT1 Record 
izes 

Incompatible Job Step Options for the Linkage Editor 52 
Linkage Editor Return Codes 

Linkage Editor ddnames 55 

ve pees amen for Object Module and Control Statement 
npu 

DCB Requirements for SYSPRINT 57 

DCB Requirements for Data Sets Used by Include and Library 

Control Statements 

Statements in the LKED Cataloged Procedure 61 
Statements in the LKEDG Cataloged Procedure 63 

Overlay Structure for INSERT Statement Example 77 
Output Load Module for ORDER Statement Example 83 
Overlay Structure for OVERLAY Statement Example 85 
Output Load Module for PAGE Statement Example 87 
Editing a Module 92 

Changing an External Reference and an Entry Point 95 
Automatic Replacement of Control Sections 

Replacing a Control Section with the REPLACE Control 
Statement 100 

Deleting a Control Section 101 

Ordering Control Sections 103 

Aligning Control Sections on Page Boundaries 104 
Diagnostic Messages Issued by the Linkage Editor 116 
Module Map 

Cross-Reference Table 118 

Load Module Format 119 

Loader Processing—SYSLIB Resolution 125 

Loader Processing~—Link Pack Area and SYSLIB 

Resolution 126 

Loader Processing—Automatic Editing 126 

Input Deck for the Loader-——Basic Format 128 

Loader and Loaded Program Data Input Stream 135 

Input Deck for a Load Job 35 

Input Deck for a Compile-Load Job 136 

Input Deck for Compilation and Loading of the Three 
Modules 137 

Using the LINK Macro Instruction to Refer to the 

Loader 139 

Using the LOAD and CALL Macro Instructions to Refer to 
HEWLOADR (Loading Without Identification) ] 

Using the LOAD and CALL Macro Instructions to Refer to 
HEWLOAD CLoading With Identification) 142 

Module Map Format Example 

Linkage Editor Output for Sample Program COBFORT 147 


Linkage Editor Output for Job Step that Created SUBONE 148 


Job Control Statements for RPLACJOB 149 

Linkage Editor Control Statements for RPLACJOB 149 
Linkage Editor Output for Sample Program RPLACJOB 150 
Overlay Tree for Multiple-Region Sample Program 
REGNOVLY 151 


Figures xiii 











56. Job Control Statements for REGNOVLY 152 | 
57. Linkage Editor Output for Sample Program REGNOVLY 154 


58. Input Statements for ITEBUPDTE Utility Program 157 f™ 
59. Job Control Statements for PARTDS 158 ‘ .¢ 
60. Linkage Editor Capacities for Minimal SIZE Values (96K ec 


bytes, 6K bytes) 160 

61. Control Section Dependencies 165 

62. Single-Region Overlay Tree Structure 166 

63. Length of an Overlay Module 7 

64. Segment Origin and Use of Storage 169 

65. Inclusive and Exclusive Segments 170 

66. Inclusive and Exclusive References 171 

67. Location of Segment and Entry Tables in an Overlay 
Module 172 

68. Control Sections Used by Several Paths 174 

69. Overlay Tree for Multiple-Region Program 175 

70. Symbolic Segment Origin in Single~Region Program 177 

71. Symbolic Segment and Region Origin in Multiple-Region 
Program 178 

72. Common Areas before Processing 183 

73. Common Areas after Processing 184 

74. Branch Sequences for Overlay Programs 187 

75. Use of the SEGLD Macro Instruction 188 

76. Use of the SEGNT Macro Instruction 189 

77. Virtual Storage Requirements 191 

78. Return Codes 


xiv MVS/7XA Linkage Editor and Loader User's Guide 











The linkage editor and the loader processing programs prepare 
the output of language translators for execution. The linkage 
editor prepares a load module that is to be brought into storage 
for execution by program fetch. The loader prepares the 
executable program in storage and passes control to it directly. 


The linkage editor provides several processing facilities, such 
as creating overlay programs and aiding program modification. 
(The linkage editor is also used to build and edit system 
libraries.) The loader provides high performance loading of 
programs that do not require the special processing facilities 
of the linkage editor. 


Use of the linkage editor is recommended in the following cases: 


@ If the program requires linkage editor services in addition 
to the MAP, LET, NCAL, and SIZE options 


e If the program uses linkage editor control statements, such 
as INCLUDE, NAME, OVERLAY 


° If a load module is to be produced for a program library 


Use of the loader is recommended if the program only requires 
the use of the following linkage editor options: MAP, LET, 
NCAL, and SIZE. Because of its fewer options and because it can 
process a job in one job step, the loader reduces editing and 
loading time by about one-half. 


Linkage editor processing is performed ina Jink-edit step. The 
linkage editor can be used for compile-link edit-go, 
compile-link edit, link-edit, and link-edit-go jobs. Loader 
processing is performed in a load step, which is equivalent to 
the link-edit-go steps. The loader can be used for compile-load 
and load jobs. 

The MVS/XA linkage editor is modified to support the following: 
e AMODE/RMODE attributes 

@ Read-only CSECT CRSECT) 


e Fill al of the high-order bit in 4-byte A-CONs and 
a Ss 


Details of how each language interfaces with the linkage editor 
can be found in the publication(s) describing that language. 


Introduction 1 
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Part I. Linkage Editor 3 


Nees 


Linkage editor processing is a necessary step that follows the 


source program assembly or compilation of any problem program. 


The linkage editor is both a processing program and a service 
program used in association with the language translators. 


Every problem program is designed to fulfill a particular 


purpose. To achieve that purpose, the program can generally be 
divided into logical units that perform specific functions. A 
logical unit of coding that performs a function, or several 
related functions, is a module. Separate functions should be 
programmed into separate modules, a process called modular 
programming. Each module can be written in the symbolic 
language that best suits the function to be performed. (The 
symbolic languages are Assembler, ALGOL, BASIC, COBOL, FORTRAN, 
PASCAL, PL/I, and RPG.) 


Each module is separately assembled or compiled by one of the 
language translators. The input to a language translator is a 

3; the output from a language translator is an 

. Before an object module can be executed, it must 
be processed by the linkage editor. The output of the linkage 
editor is a load module (Figure 1). 
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Preparing a Source Module for Execution 


An object module is in relocatable format with unexecutable 
machine code. A load module (see ™ Load Module Format®™ on 

page 118) is also relocatable, but with executable machine code. 
A load module is in a format that can be loaded into virtual 
storage and relocated by program fetch (Figure 2 on page 5). 
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Figure 2. Preparing a Source Module for Execution, and Executing the Load Module 


Any module is composed of one or more 
_ control section 1s a unit of coding (instructions and data) that 
| is, in itself, an entity. All elements of a control section are 
loaded and executed in a constant relationship to one another. 
A control section is, therefore, the smallest separately 
relocatable unit of a program. 


Each module in the input to the linkage editor may contain 
symbolic references to control sections in other modules; such 
references are called external references. These references are 
made by means of address constants (adcons). The symbol 
referred to by an external reference must be either the name of 
a control section or the name of an entry point ina control 
section. Control section names and entry names are called 
external names. By matching an external reference with an 
external name, the linkage editor resolves references between 
modules. External references and external names are called 
external symbols (Figure 3 on page 6). An external symbol is 
tert ely is defined in one module and can be referred to in 
another. 
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Figure 3. External Names and External References 
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OBJECT AND LOAD MODULES 


Object modules and load modules have the same basic logical 
structure. Each consists of 


e Control dictionaries, containing the information necessary 
to resolve symbolic cross-references between control 
sections of different modules, and to relocate address 
constants. Control dictionary entries are generated when 
external symbols, address constants, or control sections are 
processed by a language translator. Each language 
translator usually produces two kinds of control 
dictionaries: an external symbol dictionary CESD) and a 
relocation dictionary CRLD). 


® Text, containing the instructions and data of the program. 


e An end-of-module indication: an END statement in an object 
module, an end-of-module indicator in a load module. 


Each control dictionary, text, and end indication is described 
in greater detail below. 


Both object modules and load modules can contain data used by 
the linkage editor to create CSECT identification (CIDR) records. 
If the language translator creating an object module supports 
CSECT identification, the input object module can contain 
translator data for identification records on the END statement. 
Input load modules differ from object modules in the type of 


data they supply. Input load modules can also provide HMASPZAP — 


data, linkage editor data, and user data to the identification \s 
records that are built during linkage editor processing. During 
the link-edit step, the optional IDENTIFY control statement is 
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used to supply the optional user data for the CSECT 
a identification records. See "IDENTIFY Statement" on page 73 for 
( more information. 


External Symbol Dictionary 


The external symbol dictionary CESD) contains one entry for each 
external symbol defined or referred to within a module. The 
dictionary contains an entry for each external reference, 
pseudoregister (Cexternal dummy section), entry name, named or 
unnamed control section, and blank or named common area. An 
entry name, pseudoregister, or named control section can be 
referred to by any control section or separately processed 
module; an unnamed control section cannot. 


Each entry identifies a symbol, or a symbol reference, and gives 
its location, if known, within the module. Each entry in the 
external symbol dictionary is classified as one of the 
following: 





® External reference—a symbol that is defined as an external 
name in another separately processed module, but is referred 
to in the module being processed. The external symbol 
ne entry specifies the symbol; the location is 
unknown. 


e Weak external reference—a special type of external 
reference that is not to be resolved by automatic library 
call unless an ordinary external reference to the same 
symbol is found. The external symbol dictionary entry 
specifies the symbol; the location is unknown. 








® Entry name—a name that defines an entry point within a 
control section. The external symbol dictionary entry 
A specifies the symbol and its location, and identifies the 
{ control section to which it belongs. 


$ Control section name—the symbolic name of a control 
section. The external symbol dictionary entry specifies the 
symbol, the length of the control section, and its location. 
In this case, the location represents the origin of the. 
control section, which is the first byte of the control 
section. This external symbol dictionary entry may also 
specify the addressing mode and residence mode of the 
control section and whether or not the control section is 
read-only. 


e Blank or named common area——a control section used to 
reserve a virtual storage area that can be referred to by 
other modules. The reserved storage area can be used, for 
example, as a communications region within a program or to 
hold data supplied at execution time. The external symbol 
dictionary entry specifies the name, if there is one, and 
the length of the area. If there is no name, the name field 
contains blanks. 


@ Private code—an unnamed control section. This external 
symbol dictionary entry specifies the length of the control 
section and the origin. The name field contains blanks. 
The external symbol dictionary entry may also specify the 
addressing mode and residence mode of the control section 
and whether or not the control section is read-only. 


e Pseudoregister—a special facility (corresponding to the 
external dummy section feature of Assembler H Version 2) 
that can be used to write reenterable programs. 
pseudoregister is a dynamically obtained word in virtual 
storage that can be used as a pointer to dynamically 
acquired storage; that is, the space for such areas is not 
reserved in the load module but is acquired during 
execution. The external symbol dictionary contains the 
name, length, alignment, and displacement of the 
pseudoregister. 
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When processing input modules, the linkage editor resolves 
references between modules by matching the referenced symbols to 
defined symbols. To do this, the linkage editor searches for 
the external symbol definition in the external symbol dictionary 
of each input module. As shown in Figure 4, the linkage editor 
matches the external reference to Bl by locating the definition 
for Bl in the external symbol dictionary of Module B. In the 
same way, it matches the external reference to All by locating 
oe rea aad for All in the external symbol dictionary of 
odule A. 





Note: External names, including CSECT names and entry names, 
must be 1 to 8 alphameric characters in length. No leading or 
epee reba are permitted, nor are the following characters 
permitted: 


Pa ae ae 
All other characters in the 48-character set are permitted in 
any character position of the name by the linkage editor, 
including: | 

+- = . ¥ ' / and & | 
Special characters should be used with caution, however, because 


the compilers and assemblers that produce the object decks 
usually have a more limited character set. 






Input 


a / ESD for A 
Module 


Al } Control | Known 
Section 
Name 


Entry Name 


External Unknown 
Reference 









NM 
<< 
3 
Co 
2. 


; ESD for B 


Bl Control Known 
Section 
Name 
External Unknown 












CSECT Al 


‘ 
—" 





Reference 


ENTRY All 


CSECT BI 


CALL Bl CALL All 





Figure 4. Use of the External Symbol Dictionary 


Text 


The text contains the instructions and data of the module. 


Note: Object module text records may not necessarily be in 
ascending address sequence (it is possible that the language 
translator may have created them out of order). When processing 
large object modules with out-of-order text, the performance of 
the linkage editor may be improved by presorting the object 
module text in ascending address sequence (columns 6 through 8 
of the text record). 3 
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Relocation Dictionary 


The relocation dictionary (RLD) contains one entry for each 
relocatable address constant that must be modified before a 
module is executed. An entry identifies an address constant by 
indicating both its location within a control section and the 
external symbol whose value must be used to compute the value of 
the address constant. (The external symbol is defined in an 
aaa symbol dictionary entry in another control section or 
module. 





The linkage editor uses the relocation dictionary whenever it 
processes a module to adjust the address constants for 
references to other control sections and modules. This 
dictionary is also used to adjust these address constants again 
after program fetch reads an output load module from a library 
and loads it into virtual storage for execution. 


End Indication 


The end of a load module is marked by an end-of-module indicator 
CEOM). The EOM cannot, unlike the assembler END instruction, 
specify an entry point. Therefore, whenever a load module is 
reprocessed by the linkage editor, a main entry point should be 
specified on an ENTRY statement. If one is not specified, the 
linkage editor will assign the first byte of the first control 
section encountered as the entry point. The programmer will not 
usually be concerned with the format of records in the object 
oe The record formats are described in the appendix of 

fe) oO 








OCESSING 


ms This section discusses the input and output sources of the 
linkage editor, and the way in which the linkage editor produces 
1 a load module. 


INPUT AND OUTPUT SOURCES 
The linkage editor accepts two major types of input: 


e Primary input, which can contain only object modules and 
linkage editor control statements (called control statements 
in the following text). 


e Additional user-specified input, which can contain either 
object modules and control statements, or load modules. 
This input is either specified by the user as input, or 
fee ees automatically by the linkage editor from a call 
library. 


During processing, the linkage editor generates intermediate 
data. Intermediate data is placed on a direct access storage 
device when virtual storage allocated for input data is 
exhausted. 

Output of the linkage editor is of two types: 


e A load module, which is always placed ina library (a 
partitioned data set) as a named member 


e eee output, which is produced as a sequential data 
se 


Figure 5 on page 10 shows the input, intermediate, and output 
sources for the linkage editor program. 
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LOAD MODULE CREATION 


In processing object and load modules, the linkage editor 


assigns consecutive relative virtual storage addresses to all . ee 
control sections and resolves all references between control 

sections. Object modules produced by several different language 
translators can be used to form one load module. 


An output load module is composed of all input object modules 
and input load modules processed by the linkage editor. The 
control dictionaries of an output module are, therefore, a 
composite of all the control dictionaries in the linkage editor 
input. The control dictionaries of a load chats artes called the 
] icti an e relocation 
fe . The load module also contains all of the text 
from each input module, and one end-of-module indicator (see 
Figure 6 on page ll). See also ™ Load Module Format" on 
page 118 for the format of a load module. 
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Figure 5. Input, Intermediate, and Output Sources for the 
Linkage Editor 
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Assigning Addresses 


Each module to be processed by the linkage editor has an origin 
that was assigned during assembly, compilation, or a previous 
execution of the linkage editor. When several modules, each 
with an independently assigned origin, are to be processed by 
the linkage editor, the sequence of the addresses is 
unpredictable; two input modules may even have the same origin. 


Each input module can be made up of one or more control 
sections. To produce an executable output load module, the 
linkage editor assigns relative virtual storage addresses to 
each control section by assigning an origin to the first control 
section encountered and then assigning addresses, relative to 
that origin, to all other control sections to be included in the 
output load module. The value assigned as the origin of the 
control section is used to relocate each address-dependent item 
in the control section. . | 


Although the addresses in a load module are consecutive, they 
are all relative to base zero. When a load module is to be 
executed, program fetch prepares the module for execution by 
loading it at a specific virtual storage location. The 
addresses in the module are then increased by this base address. 
Each address constant must also be readjusted, another function 
of program fetch. 


Object Module A 


Output Load 
Module AB 





Figure 6. A Load Module Produced by the Linkage Editor 
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Resolving External References 


The linkage editor also resolves external references in input 
modules. Cross-references between control sections in different 

modules are symbolic. They must be resolved relative to the 
addresses assigned to the load module. The linkage editor 
calculates the new address of each relocatable expression ina 
control section and determines the assigned origin of the item 
to which it refers. 
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Linkage editor input may consist of a combination of object 
modules, load modules, and control statements. The primary 
function of the linkage editor is to combine these modules, in 
accordance with the requirements stated on control statements, 
into a single output load module. Although this linking or 
oe of modules is its primary function, the linkage editor 
also: 


® Edits modules by replacing, deleting, rearranging, and 
ordering control sections as directed by control statements 


e Aligns control sections and named common areas on GK-byte 
page boundaries as directed by control statements 


e Accepts additional input modules from data sets other than 
the a input data set, either automatically or upon 
reques 


® Reserves storage for the common control sections generated 
by Assembler and FORTRAN language translators, and static 
external areas generated by PL/I 


® Computes total length and assigns displacements for all 
pseudoregisters Cexternal dummy sections) 


die e Creates overlay programs ina structure defined by control 
( statements 


e Creates multiple output load modules as directed by control 
statements 
e Provides special processing and diagnostic output options 


® Assigns module attributes that describe the structure, 
content, and logical format of the output load module 


6 Allocates storage areas for linkage editor processing as 
specified by the programmer 


@ Stores system status index information in the directory of 
the output module library (systems personnel only) 


® Traces the processing history of a program 


e Allows the user to lengthen a control section or named 
common section without changing source code, reassembling, 
or recompiling 


® Allows the user to assign an authorization code to a load 
module that (a) makes it a restricted resource and (b) 
enables it to pass control to other restricted resources 


e Assigns an addressing mode for the main entry point, all 
true aliases, and each alternate entry point into the output 
load module 

® Assigns a residence mode for the output load module 


6 Indicates which control sections are read-only (relevant 
only in creating a nucleus load module for MVS/XA) 





Each of the linkage editor functions is described in the 
following paragraphs. 
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Links Modules 


Processing by the linkage editor makes it possible for the ao 
programmer to divide a program into several modules, which can ef 
be separately assembled or compiled, and each containing one or 7 


more control sections. The linkage editor combines these 
modules into one output load module (see Figure 7) with 
contiguous, virtual storage addresses. During processing by the 
linkage editor, references between modules within the input are 
Partie The output module is placed ina library (partitioned 
ata set). 






f rcv 
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(asm) 





Object 
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Figure 7. Linkage Editor Processing—Module Linkage 


Edits Modules 


Program modification is made easier by the editing functions of 
the linkage editor. When the functions of a program are 
changed, the programmer modifies, then compiles and link-edits 
again, only the affected control sections instead of the entire 
source module. 


Control sections can be replaced, renamed, deleted, moved, or 
ordered as directed by control statements. Control sections can 
also be automatically replaced by the linkage editor. External 
symbols can be changed or deleted as directed by control 
statements. 


Figure 8 on page 15 illustrates the module editing function of eo 
the linkage editor. ra 
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Figure 8. Linkage Editor Processing——Module Editing 


Aligns Control Sections or Common Areas on Page Boundaries 


Control sections or named common areas in the output load module 
can be aligned on 4K-byte page boundaries. Alignment on page 
boundaries enables the programmer to use real storage more 
Saree and thus appreciably reduce the paging rate for the 
job. 


Accepts Additional Input Sources 


Standard subroutines can be included in the output module, thus 
reducing the work in coding programs. The programmer can 
specify that a subroutine be included at a particular time 
during the processing of the program by using a control 
statement. When the linkage editor processes a program that 
contains this statement, the module containing the subroutine is 
retrieved from the indicated input source and made a part of the 
output module (Figure 9 on page 16). 


Symbols that are still undefined after all input modules have 
been processed cause the automatic library-call mechanism to 
search for modules that will resolve these references. When a 
module name is found that matches the unresolved symbol, the 
module is processed by the linkage editor and also becomes part 
of the output module (Figure 9). 


Note: The linkage editor distinguishes a special type of 
external reference—the weak external reference. An unresolved 
weak external reference does not cause the linkage editor to use 
the automatic library-call mechanism. Instead, the reference is 
left unresolved, and the load module is marked as executable. 
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Linkage Editor Processing—Additional Input Sources 


The linkage editor processes common control sections generated 
by the FORTRAN and Assembler language translators. The static 
external storage areas generated by the PL/I compiler are 
processed in the same way. The common areas are collected by 
the linkage editor, and a reserved virtual storage area is 
provided within the output module. 


Processes Pseudoregisters 


Pseudoregisters, like the external dummy sections of Assembler H 


Version 2,> 


aid in generating reenterable code. The linkage 


editor processes pseudoregisters by accumulating the total 
length of storage required for all pseudoregisters and recording 
the displacement of each. During execution, the program 
dynamically acquires the necessary storage. 
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Creates Overlay Programs 


To minimize virtual storage requirements, the programmer can 
organize a program into an overlay structure by dividing it into 
segments according to the functional relationships of the 
control sections. Two or more segments that need not be in 
virtual storage at the same time can be assigned the same 
relative virtual storage addresses, and can be loaded at 
different times. 





The programmer uses control statements to specify the 
relationship of segments within the overlay structure. The 
segments of the load module are placed ina library so that the 
ee eran can load them separately when the load module is 
executed. 


Creates Multiple Load Modules 


The linkage editor can also process its input to form more than 
one load module within a single job step. Each load module is 
placed in the library under a unique member name, as specified 
by a control statement. 





Provides Special Processing and Diagnostic Output Options 


The programmer can specify special processing options that 
negate automatic library call or the effect of minor errors. In 
addition, the linkage editor can produce a module map or 
cross-reference table that shows the arrangement of control 
sections in the output module and indicates how they communicate 
with one another. A list of the control statements processed 
can also be produced. 





Throughout processing, errors and possible error conditions are 
ov logged. Serious errors cause the linkage editor to mark the 
( | output module not executable. Additional diagnostic data is 
automatically logged by the linkage editor. The data indicates 
the disposition of the load module in the output module library. 


Assigns Load Module Attributes 


When the linkage editor generates a load module, it places an 
entry for the module in the directory of the library. This 
entry contains attributes that describe the structure, content, 
and logical format of the load module. The control program uses 
these attributes to determine how a module is to be loaded, what 
it contains, if it is executable, whether it is executable more 
than once without reloading, and if it can be executed by 
concurrent tasks. Some module attributes can be specified by 
the programmer; others are specified by the linkage editor as a 
result of information gathered during processing. See also 
"Assigns Addressing Mode™ on page 19, "Assigns Residence Mode" 
on page 20, and "Assigns Read-only Attribute™ on page 21. 


Allocates User-Specified Virtual Storage Areas 
The programmer can specify the total amount of virtual storage 
to be made available to the linkage editor, the amount to be 


used for the load module buffer, and the buffer for the output 
load module. 
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Stores System Status Index Information 


The following information is intended for systems personnel a o™ 
responsible for maintaining IBM-supplied load modules. It is ey 
not generally applicable to non-IBM load modules. beer 


Four bytes in the library directory entry for IBM-supplied load 
modules are used to store system status index information. This 
information, which is used for maintenance of the modules, is 
placed in the directory with a control statement. 


Traces Processing History 


Tracing the processing history of a program is simplified by the 
CSECT identification CIDR) records created and maintained by the 
linkage editor. A CSECT identification record can contain data 
that describes: 


e The language translator, its level, and the translation date 
for each control section 


e The most recent processing by the linkage editor 


e Any modification made to the executable code of any control 
section 


Optionally, user-supplied data associated with the executable 
code of a control section can also be recorded. 


Lengthens Control Sections or Named Common Sections 


The user can lengthen control sections or named common sections 
of a program to add patch space without changing the source 
code, reassembling, or recompiling. 


Added space, consisting of binary zeros, is put at the end of a . 2 
specified control section by using the EXPAND control statement Mee 
(see "Chapter 5. Specifying an Operation with Control 

Statements" on page 66). Space cannot be added to a private 

code or blank common section. 


Assigns an Authorization Code to Output Load Modules 


The authorized program facility CAPF) limits the use of 
sensitive system and Coptionally) user services and resources to 
authorized system and user programs. Authorization is defined 
as access to those services and resources. The services and 
resources to wnaee access is limited are gece in aystem 





Programs are authorized at the job-step level. For a job step 
to gain authorization initially, the first module loaded at the 
start of the job step must be an authorized module, and it must 
have been loaded from an authorized library. Otherwise, the job 
step is not authorized initially and cannot subsequently gain 
authorization. 


For a job step to maintain its authorization, all subsequent 
modules invoked during the job step (via LINK, LOAD, ATTACH, 
and/or XCTL macro instructions) must be loaded from an 
authorized library. As the authorized program executes, the 
program manager verifies that all subsequent modules for the 
program come from authorized libraries. If one or more modules 
are not APF authorized libraries, a 306 abend results. 


A library becomes an “authorized" library by the inclusion of 
its name in a list called ITEAAPF00. This list is described in 
more detail in Initialization and Tuning. 





A load module becomes "authorized" by the assignment of an 
authorization code to the load module during linkage-~editing. 
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This assignment is made via the PARM field parameter AC or via 
the control statement SETCODE, which are described in the 
sections that follow. See "SETCODE Statement™ on page 90. 


Assigns Addressing Mode 
The addressing mode (AMODE) is the attribute of an entry point 
into a load module that specifies the addressing mode in effect 
ith the load module is entered at that entry point at execution 
ime. 


The valid addressing modes are: 


24 Indicating that 24-bit addressing will be in effect 
31 Indicating that 3l-bit addressing will be in effect 
ANY Indicating that either 24-bit or 3l-bit addressing may 


be in effect 


The linkage editor determines the addressing mode for an entry 
point Ceither the main entry point, its true alias, or an 
alternate entry point) according to the following rules: 


e The linkage editor assigns a default AMODE of 24. This is 
done only in the absence of a valid, explicit specification 
of the addressing mode for the entry point. 








e The linkage editor assigns the AMODE values contained in the 
object module's ESD. These AMODE values were specified by 
the user at assembly time and represent the AMODE values 
assigned to the entry points within the CSECTs and private 
code for the module. 





@ The linkage editor assigns all the entry points into the 
a load module (the main entry point, its true aliases, and the 
( alternate entry points) the AMODE value specified as a 
parameter in the PARM field of the EXEC statement. This 
ase coda overrides the AMODE value, if any, found in the 
ata. 


e The linkage editor assigns the AMODE value specified as an 
operand on the MODE control statement to all of the entry 
points into the load module (the main entry point, its true 
aliases, and the alternate entry points). This AMODE value 
overrides any value specified as a parameter in the EXEC 
statement or any values found in the ESD data. 


The linkage editor provides the AMODE value for each entry point 
into the load module in its directory entry. In the case of a 
true alias of the main entry point or an alternate entry point, 
the directory entry contains the AMODE value for both the 
alias/alternate entry point and the main entry point. 


The AMODE value provided to the linkage editor in the ESD data 
of an object module is retained in the ESD data of the load 
module, for use in subsequent link-editing, except in the case 
of a load module built for overlay. In building a load module 
for overlay, the AMODE value in the ESD data of the load module 
is lost and can only be reintroduced by inclusion of the object 
module(€s) carrying that value. Use of the overriding AMODE 
specifications (the parameter in the PARM field of the EXEC 
statement or the operand in the MODE control statement) 
establishes the AMODE value carried in the directory entry, but 
does not affect the ESD data. 


All entry points in load modules built for overlay are assigned 
an AMODE of 24, regardless of the ESD data, the PARM field 
parameter, or the MODE statement operand. 





Chapter 2. Uses of the Linkage Editor 19 








Assigns Residence Mode 





The residence mode (RMODE) is the attribute of a load module eC 
that specifies the residence mode of a load module when it is ‘ay 
loaded into virtual storage for execution. 


; The valid pasvdence modes are: 


24 | Indicating that the woadie must reside within 24-bit 
addressable virtual storage (that is, below the 
16-megabyte virtual storage line) 


ANY Indicating that the module may reside anywhere in 
virtual storage (that is, either above or below the 
16-megabyte virtual storage line) 


The linkage editor determines the residence mode for a load 
module according to the following rules: 


@ The linkage editor assigns a default RMODE of 24. This 
occurs only in the absence of a valid explicit specification 
of the residence mode for the load module. 


e The linkage editor assigns the RMODE specified in the object 
module. This RMODE value is specified by the user to the 
assembler for the control section or private code. The 
RMODE value passes to the linkage editor in the ESD data. 

The linkage editor assigns the RMODE value taken from the 
control section or private code that contributes to the 
output load module, ignoring identically named control 
sections and private code that are replaced or deleted. 


e As the control sections and private code that contribute to 
the output load module are processed, the RMODE value for 
the load module, based on the ESD data, is accumulated on a 
"most restrictive" basis. This means: 


= If any section in the load module has an RMODE of 24, ee, 
the RMODE for the load module is 24. | 


- If all sections in the load module have an RMODE of ANY, 
the RMODE for the load module is ANY. 


® The linkage editor assigns to the load module the RMODE 
value specified as a parameter in the PARM field of the EXEC 
statement. This RMODE value overrides the RMODE value, if 
any, found in the ESD data. 


e The linkage editor assigns to the load module the RMODE 
value specified as an operand on the MODE control statement. 
This RMODE value overrides the RMODE value, if any 
specified as a parameter in the PARM field of the EXEC 
leat as well as the RMODE value, if any, found in the 
ata. 


Load modules built for overlay are assigned an RMODE of 24, 
regardless of the ESD data, the PARM field parameter, or the 
MODE statement operand. ? | 


The linkage editor provides the RMODE value for the load module 
in each directory entry applicable to that load module. 


Except in the case of a load module built for overlay, the RMODE 
value provided to the linkage editor in the ESD data of an 
object module is retained in the ESD data of the load module, 
for use in subsequent link-editing. In building a load module 
for overlay, the RMODE value in the ESD data of the load module 
is lost and can only be reintroduced by inclusion of the object 
module(€s) carrying that value. Use of the overriding RMODE 
specifications (the parameter in the PARM field of the EXEC 
statement or the operand in the MODE control statement) 
establishes the RMODE value carried in the directory entry, but 
does not affect the ESD data. 
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AMODE/RMODE Hierarchy 


The following hierarchy is used to determine the addressing and 
residence modes of the linkage editor output: 


1. Value on the linkage editor MODE statement 

2. Value of the parm field on the EXECUTE statement 

3. Value in the ESD data produced by the AMODE= or RMODE= 
assembler statement 

4. Default value of 24 


Note: An overlay module always results in an AMODE of 24 and an 
RMODE of 24. A load module produced from multiple object 
modules results in an RMODE of 24, if any one of the object 
modules has an RMODE of 24. 


Assigns Read-only Attribute 


A read-only control section CRSECT) is defined by the user in 
the source language which assembles the control section. The 
assembler indicates in the external symbol dictionary entry for 
the control section that it is read-only. The linkage editor 
Niclas a indication in the scatter table for the output 

oad module. 


The indication of the read-only attribute is relevant only to 
the nucleus initialization program in MVS/XA. In all other 
cases it is ignored. 


Time Sharing Option 


The linkage editor has the same relationship to the operating 
system as any other processing program. It can be executed 
either as a job step, a subprogram, or a subtask. Control is 
passed to the linkage editor in one of three ways: 


e As a job step, when the linkage editor is specified on an 
EXEC job control statement in the input stream 


e As a subprogram, with the execution of a CALL macro 
eastruction Cafter the execution of a LOAD macro 
instruction), a LINK macro instruction, or an XCTL macro 
instruction 


e As a subtask, in multitasking systems, with the execution of 
the ATTACH macro instruction 


Execution of the linkage editor and the data sets used by the 
linkage editor are described to the system with job control 
language statements. These statements describe all jobs to be 
performed by the system. 


Note: Job control statements should not be confused with 
linkage editor control statements. Job control statements are 
processed before the linkage editor is executed; linkage editor 
sahara statements are processed during linkage editor 
execution. 


(TSO) 


When the linkage editor is used under TSO, it is invoked by the 
linkage editor prompter program that acts as an interface 
between the user, the operating system, and the linkage editor. 
Under TSO, execution of the linkage editor and definition of 
data sets used by the linkage editor are described to the system 
through use of the LINK command that causes the prompter to be 
executed. Operands of the LINK command can also be used to 
specify the linkage editor options a job requires. Complete 
procedures for use of the LINK command are given in 
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The ignkage editor accepts input from two major sources: the 
primary input data set and additional data sets. The primary 
is made available through job control statements. 
are made available either through the 
automatic library call mechanism, or through user-specified 
control statements. They must, however, also be defined with 
job control statements. 


Primary and additional input data sets may contain the following 
types of data: 


® One or more object modules 
e One or more load modules 
e Control statements 


e Combinations of the above (restrictions on certain 
combinations are noted where they apply) 


Object modules and control statements may be contained in either 
sequential or partitioned data sets. Load modules must be 
contained in partitioned data sets. 


This chapter describes the "linking" functions of the linkage 
editor only; the "editing" functions are described in "Chapter 
6. Editing a Control Section" on page 92. 


PRIMARY INPUT DATA SET 


OBJECT MODULES 


The primary input data set is required for every linkage editor 
job step. It must be defined by a DD statement with the ddname 
SYSLIN. The primary input can be: 


e A sequential data set 
® A member of a partitioned data set 


® A concatenation of sequential data sets and/or members of 
partitioned data sets 


The primary input data set must contain object modules and/or 
control statements. The modules and control statements are 
processed sequentially and their order determines the basic 
order of linkage editor processing during a given execution. 
However, the order of the control sections after processing does 
not i ak reflect the order in which they appeared in the 
input. 


In the examples that follow, only the statements necessary to 
define the input to the linkage editor are shown; complete 
examples are shown in "Appendix A. Sample Linkage Editor 
Programs” on page 145 


The primary input to the linkage editor may consist solely of 
one or more object modules. The rest of this section discusses 
object module input from cards, as a member of a partitioned 
data set, passed from a previous job step, or created in a 
separate job. 
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From Cards 


es Object module input to the linkage editor may be on cards. The 
card deck itself is treated as a sequential data set; the cards 
Pe aie in the input stream, after a DD ® statement, as 
ollows: 


7/SYSLIN DD 
Object Deck A 


Object Deck B 
1% 





The card input is followed by a /X% statement. 


An example of the JCL when card decks are used in addition to 
other input is as follows: 





S/SYSLIN DD DSNAME=INPUT,... 
A DD % 
Object Deck A ) 


Object Deck B 
7% 








By omitting the ddname on the second DD statement, the card 
Mie enone to the data set described on the SYSLIN DD 
statemen 


As a Member of a Partitioned Data Set 


An object module in a partitioned data set can be used as 
primary input to the linkage editor by specifying its data set 
name and member name on the SYSLIN DD statement. In the 
following example, the member named TAXCOMP in the object module 
library LIBROUT is to be the primary input; LIBROUT is a 
cataloged data set: 


“7SYSLIN DD DSNAME=LIBROUTCTAXCOMP), 
17 


DISP=( OLD, KEEP) 





uns library member is processed as if it were a sequential data 
set. 


Members of partitioned data sets can be concatenated with other 
input data sets, as follows: 


“/SYSLIN DD DSNAME=OBJLIB, DISP=(OLD,KEEP),... 
// DD DSNAME=LIBROUTCTAXCOMP), 


17 DISP=COLD, KEEP) 





Library member TAXCOMP is concatenated to data set OBJLIB; 
ee they are the primary input, both must contain object 
modules. 
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Passed from a Previous Job Step 


An object. module to be used as input can be passed from a 
previous job step to a linkage editor job step in the same job, 
as in a compile-link-edit job. That is, the output from the 
compiler is direct input to the Linkage editor. In the 
following example, an object module that was created in a 
previous job step (STEPA) is passed to the linkage editor job 
step CSTEPB): 


STEPA 

//SYSGO DD DSNAME=&&OBJECT, DISP=CNEW,PASS),... 
STEPB 

S/SYSLIN DD DSNAME=&& OBJECT, DISP=COLD, DELETE) 


The data set name &&O0BJECT, used in both job steps, identifies 
the object module as the output of the language processor on the 
SYSGO DD statement, and as the primary input to the linkage 
editor on the SYSLIN DD statement. 


Note: The double ampersand (&&) in the data set name defines a 
temporary data set. These data sets exist for the duration of 
the job and are automatically deleted at the end of the job. If 
the data set is to be preserved for longer than the duration of 
a single job, the double ampersand is not used (DSNAME=OBJECT). 


The method used in the preceding example can also be used to 
retrieve object modules created in previous steps. If the same 
data set name is used for the output of each language processor, 


one SYSLIN DD statement can be used to retrieve all the object 
modules, as follows: 


STEPA: 
4/3SYSGO DSNAME=&&0BJMOD, DISP=CNEW,PASS),... 


STEPB: 


7/SYSPUNCH DD DSNAME=&&0BJMOD, DISP=C(MOD, PASS) 


STEPC: 
S/SYSLIN DD DSNAME=&&OBJMOD, DISP=COLD, DELETE) 





The two object modules from STEPA and STEPB are placed in the 
same sequential data set, &&OBJMOD. The SYSLIN DD statement in 
STEPC causes both object modules to be used as the primary input 
to the linkage editor. 


Another method can be used to accomplish this purpose: 
concatenation of data sets. This method could be used if the 
object modules were created in previous job steps with different 
member names, as follows: 
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STEPA: 


//SYSGO DSNAME=&&0BJLIBCMODA), DISP=C(NEW, 
// PASS),... 


STEPB: 
//SYSPUNCH DSNAME=&&0BJLIBCMODB), DISP=CMOD, 
1? PASS),... 


STEPC: 


4/SYSLIN BorETED =&S&0BJLIBCMODA), DISP=COLD, 
17 

// DSNAME=&&O0BJLIBCMODB), DISP=COLD, 
// DELETE) , VOL=REF=%. STEPB. SYSPUNCH 





The object modules created in STEPA and STEPB were placed in a 
partitioned data set with different member names. e two 
members are concatenated in STEPC as primary input. Each member 
is considered to be a sequential data set. 


Created in a Separate Job 


CONTROL STATEMENTS 


If the only input to the linkage editor is an object module from 
a previous job, the SYSLIN DD statement contains all the 
information necessary to locate the object module, as follows: 


S/SYSLIN DD DSNAME=OBJECT, DISP=COLD, DELETE), 
17 


UNIT=3350, VOLUME=SER=LIB615 





An object module created in a separate job may also be on cards, 
in which case it is handled as described earlier. 


The primary input data set may also consist solely of control 
statements. When the primary input is control statements, input 
modules are specified on INCLUDE control statements (see 
"Included Data Sets" on page 32). The control statements may be 
a placed in the input stream or stored in a permanent data 
set. 


In the following example, the primary input consists of control 
statements in the input stream: 


S/SYSLIN 


DD x 
paosage Editor Control Statements 
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In the next example, the primary input consists of control 
statements stored in the member INCLUDES in the partitioned data 


set CTLSTMTS: «~ 


\ ed 


//SYSLIN DD DSNAME=CTLSTMTSCINCLUDES), DISP=COLD, 
1/ ais | 


KEEP),. 





In either case, the control statements can be any of those 
described in "Chapter 5. Specifying an Operation with Control 
eae on page 66, as long as the rules given there are 
ollowed. 


OBJECT MODULES AND CONTROL STATEMENTS 


The primary input to the linkage editor may contain both object 
modules and control statements. The object modules and control 
statements may be in either the same data set or in different 
data sets. If the modules and statements are in the same data 
set, this data set is described on the SYSLIN DD statement as 
any data set is described. 


If the modules and statements are in different data sets, the 

data sets are concatenated. The control statements may be 

defined either in the input stream or as a separate data set. 
Control Statements in the Input Stream 


Control statements can be placed in the input stream and 
concatenated to an object module data set, as follows: es 


4/SYSLIN DD DSNAME=&&OBJECT,... 
/7/ DD ¥ 


Linkage Editor Control Statements 
7% 





Another method of handling control statements in the input 
stream is to use the DDNAME parameter, as follows: 


S/SYSLIN DD DSNAME=&&OBJECT,... 
// DD DDNAME=SYSIN | 


“/SYSIN DD % 
Linkage Editor Control Statements 
/% 





Note: The linkage editor cataloged procedures use DDNAME=SYSIN 
for the SYSLIN DD statement to allow the programmer to specify 
the primary input data set required. 
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Control Statements in a Separate Data Set 


A separate data set that contains control statements may be 
concatenated to a data set that contains an object module. The 
control statements for a frequently used procedure (for example, 
a complex overlay structure or a series of INCLUDE statements) 
can be stored permanently. In the following example, the 
members of data set CTLSTMTS contain linkage editor control 
Beaniccn One of the members is concatenated to data set 





4/SYSLIN DD DSNAME=&&OBJECT, DISP=COLD, DELETE),.. 
4/ 


DD DSNAME=CTLSTMTSCOVLY), DISP=COLD, 
// KEEP),... 





The control statements in the member named OVLY of the 
spi heatith aa data set CTLSTMTS are used to structure the object 
module. 


AUTOMATIC LIBRARY CALL 


The automatic library-call mechanism is used to resolve external 
references that were not resolved during primary input 
processing. Unresolved external references found in modules 
from additional data sources are also processed by this 
mechanism. 





\ 


Note: The following discussion of automatic library call does 
not lil het unresolved weak external references; they are left 
unresolved. 


( | The automatic library-call mechanism involves a search of the 
; directory of the automatic call library for an entry that 
matches the unresolved external reference. When a match is 
ty oe the entire member is processed as input to the linkage 
editor. 


Automatic library call can resolve an external reference when 
the following conditions exist: The external reference must be 
€1) a member name or an alias of a module in the call library, 
and €2) it must be defined as an external name in the external 
symbol dictionary of the module with that name. If the 
unresolved external reference is a member name or an alias in 
the library, but is not an external name in that member, the 
member is processed but the external reference remains 
unresolved unless subsequently defined. 


The automatic library-call mechanism searches the call library 
defined on the SYSLIB DD statement. The call library can 
contain either (1) object modules and control statements or (2) 
load modules; it must not contain both. 


Modules from libraries other than the SYSLIB call library can be 
searched by the automatic library-call mechanism as directed by 
the LIBRARY control statement. The library specified in the 
control statement is searched for member names that match 
specific external references that are unresolved at the end of 
input processing. If any unresolved references are found in the 
modules located by automatic library call, they are resolved by 
another search of the library. Any external references not 
specified on a LIBRARY control statement are resolved from the 
library defined on the SYSLIB DD statement. 


5 In addition, two means exist to negate the automatic 

. library-call mechanism. The LIBRARY statement can be used to 

. negate the automatic library call for selected external 

P references unresolved after input processing; the NCAL option on 
the EXEC statement can be used to negate the automatic library 
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call for all external references unresolved after input 
processing. Use of the LIBRARY control statement and the NCAL Pan 
option are discussed after the SYSLIB DD statement following. —— 


SYSLIB DD STATEMENT 


If the automatic library-call mechanism is to be used, the call 
library must be a partitioned data set described by a DD 
statement with a ddname of SYSLIB. Details concerning DCB 
requirements and record formats for SYSLIB libraries are given 
in "SYSLIB DD Statement" on page 56. The call library may be 
either a system call library or a private call library; call 
libraries may be concatenated. 


System Call Library 


For an example of some of the system programs that have their 
own automatic call library, see Figure 10. This library must be 
defined when an object module produced by that assembler or 
compiler is to be link-edited. 


ALGOL SYS] .ALGLIB 
COBOL SYS1.COBLIB 


FORTRAN SYS1.FORTLIB 


Figure 10. System Automatic Call Libraries 





The call library may contain input/output, data conversion, 
and/or other special routines (such as Sort/Merge SYS1.SORTLIB) 
that are needed to complete the module. The assembler or 
compiler creates an external reference for these special 
routines and the linkage editor resolves the references from the 
appropriate call library. 


In the following example, a FORTRAN object module created in 


STEPA is to be link-edited in STEPB, and the FORTRAN automatic 
call library is used to resolve external references: 


STEPA: 
“/SYSOBSJ DSNAME=&&OBJMOD, DISP=CNEW, 
17 PAS 


Doses 


STEPB: 


//7SYSLIN DSNAME=&&OBJMOD, DISP=COLD, DELETED 
S/SYSLIB DSNAME=SYS1.FORTLIB, DISP=SHR 





The disposition of SHR on the SYSLIB DD statement means that 
other tasks that may be executing concurrently with STEPB may 
also use SYS]1.FORTLIB. 
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Private Call Libraries 


The SYSLIB DD statement can also describe a private, 
user-written library. In this case, the automatic library-call 
mechanism searches the private library for unresolved external 
references. In the following example, unresolved external 
ereocana = are to be resolved from a private library named 

2 





“/SYSLIB DD DSNAME=PVTPROG, DISP=SHR,UNIT=3350, 
174 


VOLUME=SER=PVT002 





Concatenation of Call Libraries 


System call libraries and private call libraries may be 
concatenated either to themselves, and/or to each other. When 
libraries are concatenated, they must all be either object 
sara libraries or load module libraries; they may not be 
mixed. 





If object modules from different system processors are to be 
link-edited to form one load module, the call library for each 
must be defined. This is accomplished by concatenating the 
additional call libraries to the library defined on the SYSLIB 
DD statement. In the following example, a FORTRAN object module 
and a COBOL object module are to be link-edited; the two system 
call libraries are concatenated as follows: 





( ; //SYSLIB DD DSNAME=SYS1.FORTLIB, DISP=SHR 
i 4/4 


DD DSNAME=SYS1.COBLIB, DISP=SHR 





System libraries are cataloged; no unit or volume information is 
needed. 


A system call library and a private call library can also be 
concatenated in this way. For example, by adding the following 
statement to the two in the preceding example, the private call 
library PVTPROG, which is not cataloged, is concatenated to the 
two system call libraries: 


DSNAME=PVTPROG, DISP=SHR, UNIT=3350, 


VOLUME=SER=PVT002 





Any external references not resolved from the two system 
libraries are resolved from the private library. 


LIBRARY CONTROL STATEMENT 


The LIBRARY control statement can be used to direct the 
automatic library-call mechanism to a library other than that 
specified in the SYSLIB DD statement. Only external references 
listed on the LIBRARY statement are resolved in this way. All 
other unresolved external references are resolved from the 
library in the SYSLIB DD statement. 
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The LIBRARY statement can also be used to specify external 
references that are not to be resolved by the automatic 


library-call mechanism. The LIBRARY statement specifies the f 
duration of the nonresolution: either during the current ay 
linkage editor job step, called j =< 3 or during : 


this or any subsequent linkage editor job step, called 
never-cal]. 


Examples of each use of the LIBRARY statement follow; a 
se ad of the format is given in "LIBRARY Statement™ on 
page ; 


Additional Call Libraries 


If the additional libraries are to be used to resolve specific 
references, the LIBRARY statement contains the ddname of a DD 
statement that describes the library. The LIBRARY statement 
also contains, in parentheses, the external references to be 
resolved from the library; that is, the names of the members to 
be used from the library. If the unresolved external reference 
is not a member name in the specified library, the reference 
remains unresolved unless subsequently defined. 


For example, two modules (DATE and TIME) from a system call 
library have been rewritten. The new modules are to be tested 
with the calling modules before they replace the old modules. 
Because the automatic library call mechanism would otherwise 
search the system call library (which is needed for other 
modules), a LIBRARY statement is used, as follows: 


“/7SYSLIB DSNAME=SYS1 .COBLIB, DISP=SHR 

//TESTLIB DSNAME=TEST,DISP=COLD,KEEP),... 

“7 SYSLIN DSNAME=ACCTROUT,... = 
/ : 


/ D ¥ 
geen es TESTLIBCDATE, TIME) \ 





Two external references, DATE and TIME, are resolved from the 
library described on the TESTLIB DD statement. All other 
unresolved external references are resolved from the library 
described on the SYSLIB DD statement. 


Restricted No-Call Function 


The programmer can use the LIBRARY statement to specify those 
external references in the output module for which there is to 
be no library search during the current linkage editor job step. 
This is done by specifying the external reference(s) in 
parentheses without specifying a ddname. The reference remains 
unresolved, but the linkage editor marks the module executable. 


For example, a program contains references to two large modules 
that are called from the automatic call library. One of the 
modules has been tested and corrected; the other is to be tested 
in this job step. Rather than execute the tested module again, 
the restricted no-call function is used to prevent automatic 
library call from processing the module as follows: 


af 
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Never-Call Function 


NCAL OPTION 





77 E PGM=HEWL , PARM=LET 
“/SYSLIB D DSNAME=PVTPROG, DISP=SHR, UNIT=3550, 
17 


VOLUME=SER=PVT002 


//SYSLIN ) DSNAME=8&PAYROL,... 
aA DD x 
LIBRARY COVERTIME) 
x 





As a result, the external reference to OVERTIME is not resolved 
by automatic library call. 


The never-call function specifies those external references that 
are not to be resolved by automatic library call during this or 
any subsequent linkage editor job step. This is done by 
specifying an asterisk followed by the external reference(s) in 
parentheses. The reference remains unresolved but the linkage 
editor marks the module executable. 


For example, a certain part of a program is never executed, but 
it contains an external reference to a large module (CITYTAX) 
which is no longer used by this program. However, the module is 
in a call library needed to resolve other references. Rather 
than take up storage for a module that is never used, the 
never-call function is specified, as follows: 


17 EXEC PGM=HEWL,PARM=LET 
“/SYSLIB DD DSNAME=PVTPROG, DISP=SHR, UNIT=3550, 
77 VOLUME=SER=PVT002 


//SYSLIN DD DSNAME=TAXROUT, DISP=OLD,... 
ft x 

LIBRARY ¥(CITYTAX) 
7% 





As a result, when program TAXROUT is link-edited, the external 
reference to CITYTAX is not resolved by automatic library call. 


When the NCAL option is specified, no automatic library call 
occurs to resolve external references that are unresolved after 
input processing. The NCAL option is similar to the restricted 
no-call function on the LIBRARY statement, except that the NCAL 
option negates automatic library call for all unresolved 
external references and restricted no-call negates automatic 
library call for selected unresolved external references. With 
NCAL, all external references that are unresolved after input 
processing is finished, remain unresolved. The module is, 
however, marked executable. 


The NCAL option is a special processing parameter that is 


specified on the EXEC statement as described in "No Automatic 
Library-Call Option" on page 43. 
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The INCLUDE control statement requests the linkage editor to use 
additional data sets as input. These can be sequential data 
sets containing object modules and/or control statements, or 
members of partitioned data sets containing object modules 
and/or control statements, or load modules. 


The INCLUDE statement specifies the ddname of a DD statement 
that describes the data set to be used as additional input. If 
the DD statement describes a partitioned data set, the INCLUDE 
statement also contains the name of each member to be used. See 
"INCLUDE Statement™ on page 75 for a detailed description of the 
format of the INCLUDE statement. 


When an INCLUDE control statement is encountered, the linkage 


editor processes the module or modules indicated. Figure ll 


shows the processing of an INCLUDE statement. In the 
illustration, the primary input data set is a sequential data 
set named OBJMOD which contains an INCLUDE statement. After 
processing the included data set, the linkage editor processes 
the next primary input item. The arrows indicate the flow of 
processing. 


If an included data set also contains an INCLUDE statement, this 
specified module is also processed. However, any data following 
the INCLUDE statement is not processed. 


If the OBJMOD data set shown in Figure 11 is itself included, 
the data following the INCLUDE statement for OBJLIB is not 
processed. Figure 12 on page 33 shows the flow of processing 
for this example. 


Primary Input 
Data Set OBJMOD 





Library OBJLIB 
Member MODA 


Include OBJLIB (MODA) 


Figure 11. Processing of One INCLUDE Control Statement 
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Figure 12. Processing of More than One INCLUDE Control Statement 


Including Sequential Data Sets 


Sequential data sets containing object modules and/or control 
statements can be specified by an INCLUDE control statement. In 
the following example, an INCLUDE statement specifies the 

arth ie of two sequential data sets to be used as additional 
LTnput: 


// ACCOUNTS DD DSNAME=ACCTROUT, DISP=COLD,KEEP),... 
//INVENTRY DD DSNAME=INVENTRY,DISP=COLD,KEEP),... 
S/SYSLIN DD DSNAME=QTREND,... 

1/7 


DD % 
INCLUDE ACCOUNTS, INVENTRY 
/* 





Each ddname could also have been specified on a separate INCLUDE 
statement; with either method, a DD statement must be specified 
for each ddname. 


Another method of doing the preceding example is given in 
"Including Concatenated Data Sets™ on page 34. 





Chapter 3. Defining Input to the Linkage Editor 33 








Including Library Members 





One or more members of a partitioned data set can be specified 
on an INCLUDE control statement. The member name must be 
specified on the INCLUDE statement; no member name should appear 
on the DD statement itself. 


In the following example, one member name is specified on the 
INCLUDE statement: | 


//PAYROLL DD DSNAME=PAYROUTS, DISP=COLD,KEEP),... 
geen DD DSNAME=&&CHECKS, DISP=COLD, DELETE),... 
% 


/ DD 
INCLUDE PAYROLLCFICA) 
X 





If more than one member of a partitioned data set is to be 
included, the INCLUDE statement specifies all the members to be 
used from each library. The member names appear in parentheses, 
following the data set name of the library. The member names 
are not repeated on the DD statement. 


In the following example, an INCLUDE statement specifies two 
pe from each of two libraries to be used as additional 
input: 


//PAYROLL DD DSNAME=PAYROUTS, DISP=COLD,KEEP),... 
// ATTEND DD DSNAME=ATTROUTS, DISP=COLD,KEEP),... 
//SYSLIN DD X 


INCLUDE PAYROLL CFICA, TAX), ATTENDCABSENCE, OVERTIME) 
7K 





Each library could have been specified on a separate INCLUDE 
statement; with either method, a DD statement must be specified 
for each ddname. 


Another method of doing this example is given in "Including 
Concatenated Data Sets." 


Including Concatenated Data Sets 


Several data sets can be designated as input with one INCLUDE 
statement that specifies one ddname; additional data sets are 
then concatenated to the data set described on the specified DD 
statement. When data sets are concatenated, all records must 
have the same characteristics (that is, format, record length, 
block size, etc.) 


SEQUENTIAL DATA SETS: In the following example, two sequential 
data sets are concatenated and then specified as input with one 
INCLUDE statement: | 


//CONCAT DD DSNAME=ACCTROUT, DISP=(OLD,KEEP),... 
17 DD DSNAME=INVENTRY, DISP=COLD,KEEP),... 
“7 SYSLIN ; DSNAME=SALES,DISP=OLD,... 
7/7 


D * 
INCLUDE CONCAT 
7K | 
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When the INCLUDE statement is recognized, the contents of the 
sequential data sets ACCTROUT and INVENTRY are processed. 


LIBRARY MEMBERS: Members from more than one library can be 
designated as input with one ddname on an INCLUDE statement. In 
this case, all the members are listed on the INCLUDE statement; 


the partitioned data sets are concatenated using the ddname from 
the INCLUDE statement: 


//CONCAT DD DSNAME=PAYROUTS, DISP=(OLD,KEEP),... 
17 DD DSNAME=ATTROUTS, DISP=COLD,KEEP),.. 

Z/SYSLIN DD DSNAME=REPORT,DISP=OLD,... 
47 


DD * 
cenehy es CONCATCFICA, TAX, ABSENCE, OVERTIME) 





When the INCLUDE statement is recognized, the two libraries, 
PAYROUTS and ATTROUTS, are searched for the four members; the 
members are then processed as input. 
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- This chapter summarizes those aspects of the job control 


language that pertain directly to the use of the linkage editor. 
The major topics covered are the EXEC statement, DD statements, 
and cataloged procedures for the linkage editor. The reader 
should be familiar with the job control language as described in 
the publication JCL 


EXEC STATEMENT-~INTRODUCTION 


The EXEC statement is the first etatenent of every job step. 
For the linkage editor job step, the following topics are 
pertinent: | 

e° The program name of the linkage editor 

e Linkage editor options passed to the job step 

e Region-~size requirements for the linkage editor 


For an execution job step following the linkage editor job step, 
the linkage editor return code is important. 


The EXEC statement contains the symbolic name of the load module 
to be invoked for execution. The linkage editor can be invoked 
with the following program name: 

HEWL 


LINKEDIT is an alias name for the linkage editor and can also be 
used to invoke it. 


For example, the following EXEC statement causes the linkage 
editor to be invoked: 


//\LKED EXEC PGM=HEWL 
PGM=LINKEDIT could also be used. 
To ensure compatibility with the operating system, the linkage 


editor can also be invoked by any of the following alias names: 
ITEWL, IEWLF4940, IEWLF880, and IEWLF128. 


EXEC STATEMENT“—JOB STEP OPTIONS 


The EXEC statement also contains a list of options or parameters 
be be passed to the linkage editor. These options are of four 
ypes: 


° Module attributes, which describe the characteristics of the 
output load module | 


® Special processing options, which affect linkage editor 
processing 


6 Space allocation options, which affect the amount of storage 
used by the linkage editor for processing and output module 
library buffers 


e Output options, which specify the kind of output the linkage 
editor is to produce 


The rest of this section describes the options in each category. 
All the options for a particular linkage editor execution are 
listed in the PARM parameter on the EXEC statement. They can be 
listed in any sequence, as long as the rules for coding 
parameters are followed. 
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MODULE ATTRIBUTES 


The module attributes describe the characteristics of the output 
module, or modules. CIf more than one load module is produced 
by the same linkage editor job step, all output modules will 
have the attributes assigned on the EXEC statement.) The 
attributes for each load module are stored in the directory of 
the output module library along with the member name. (The 
format of the pice entry of a partitioned data set is given 
in Data Areas—JES3. 





Module attributes specify whether or not the module: 
@ Can ever be processed by the linkage editor 


@ Can be brought into virtual storage only by the LOAD macro 
instruction 





e Is to be in overlay format 


e Can be reused 





e Can be placed in the link pack area; that is, is reenterable 


® Can be replaced during execution by recovery management; 
that is, is refreshable 


® Is to be tested by the TSO TEST command 


e Is to have specified control sections aligned on page 
boundaries 


e Is or is not authorized to use the restricted system 
resources and functions 


_ After the descriptions of the module attributes, the default and 
( : incompatible attributes are discussed. 


| Downward Compatible Attribute 


When this attribute is specified, a maximum record size of 1024 
bytes is used for the output module library. 


To assign the downward compatible attribute, code DC in the PARM 
field as follows: 


//\LKED EXECPGM=IEWL,PARM="DC,...°* 


Note: If the DC attribute is specified and the output 
load module library is a data set created by the lLinkedit 
job step, the blacksize in the data set control block 
CDSCB) is set to 1024. If the DC attribute is specified 
and the output load module library is an existing data 
set, then the blocksize in the DSCB is set to 1024, but 
only if the current blocksize in the DSCB is less than 
1024. If the current blocksize in the DSCB is greater 
than 1024, the load module is written using a maximum 
record size of 1024 bytes; the blocksize in the DSCB is 
not changed. 


Scatter Format Attribute 
When the scatter format attribute is specified, the linkage 
editor produces a load module in a format suitable for either 


scatter or block loading. 


To assign the scatter format attribute, code SCTR in the PARM 
field, as follows: 


//\LKED EXEC PGM=IEWL,PARM='SCTR,...' 
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Notes: 


1. If scatter format is not specified, the block format | fA ™ 
attribute is assigned by the linkage editor. (The \ * 
programmer cannot specify block format. ) aac 


2. If SCTR is specified, the programmer should ensure that the 
load module does not contain zero-length control sections, 
private code sections, or common areas. The presence of 
such sections in a module that is to be scatter loaded can, 
under certain circumstances, cause the module to be loaded 
incorrectly. 


3. The SCTR attribute must be specified when the nucleus for a 
VS system is link-edited. In all other instances, if the 
SCTR attribute is specified, the linkage editor builds the 
output load module appropriately; however, scatter load 
support is not provided in VS systems and the attribute/load 
module format is ignored when fetching the load module. 


Not Editable Attribute 


A load module which is marked NE Cnot editable) is not 
reprocessable by the linkage editor. If a module map or a 
ee table is requested, the not-editable attribute 
is ignored. 


To assign the not-editable attribute, code NE in the PARM field, 
as follows: 


//LKED EXEC PGM=HEWL,PARM="'NE,...° 


Note: The not-editable attribute disables the EXPAND function 
for the output load module and also limits to 18 the number of 
consecutive iterations of AMASPZAP. If the EXPAND function is 
required or more than 18 iterations of AMASPZAP are required, 
the load module must be re-created. 


Only-Loadable Attribute 


A module with the only-loadable attribute can be brought into 
virtual storage only with a LOAD macro instruction. Some 
subsets of the control program use a smaller control table when 
the load module is invoked with a LOAD. This reduces the 
overall virtual storage requirements of the module. 


The module with the only-loadable attribute must be entered by 
means of a branch instruction or a CALL macro instruction. If 
an attempt is made to enter the module with a LINK, XCTL, or 
ATTACH macro instruction, the program making the attempt is 
terminated abnormally by the control program. 


To assign the only-loadable attribute, code OL in the PARM field 
as follows: 


4/LKED EXEC PGM=HEWL,PARM="OL,...' 


Overlay Attribute 


A program with the overlay attribute is placed in an overlay 
structure as directed by linkage editor OVERLAY control 
statements. The module is suitable only for block loading; it 
cannot be refreshable, reenterable, or serially reusable. 


If the overlay attribute is specified and no OVERLAY control 
statements are found in the linkage editor input, the attribute 
is negated. The condition is considered a recoverable error; 
that is, if the LET option is specified, the module is marked 
executable. 
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The overlay attribute must be specified for overlay processing. 
If this attribute is omitted, the OVERLAY and INSERT statements 
are considered invalid, and the module is not an overlay 
structure. This condition is also recoverable; if the LET 
option is specified, the module is marked executable. 


To assign the overlay attribute, code OVLY in the PARM field as 
follows: 


//\KED EXEC PGM=HEWL,PARM="OVLY,...' 


See "Appendix C. Designing and Specifying Overlay Programs" on 
page 163 for information on the design and specification of an 
overlay structure. 


Reusability Attributes 


Either one of two attributes may be specified to denote the 
reusability of a module. (Reusability means that the same copy 
of a load module can be used by more than one task either 
concurrently or one at a time.) The reusability attributes are 

and serially reusable; if neither is specified, the 
module is not reusable and a fresh copy must be brought into 
virtual storage before another task can use the module. 








The linkage editor only stores the attribute in the directory 
entry; it does not check whether the module is really 
reenterable or serially reusable. A reenterable module is 
automatically assigned the reusable attribute. However, a 
reusable module is not also defined as reenterable; it is 
reusable only. 


REENTERABLE: <A module with the reenterable attribute can be 
executed by more than one task at a time; that is, a task may 
begin executing a reenterable module before a previous task has 
finished executing it. This type of module cannot be modified 
by itself or by any other module during execution. 


If a module is to be reenterable, all the control sections 
within the module must be reenterable. If the reenterable 
attribute is specified, and any load modules that are not 
reenterable become a part of the input to the linkage editor, 
the attribute is negated. 


To assign the reenterable attribute, code RENT in the PARM 
field, as follows: 


//LKED EXEC PGM=HEWL,PARM="RENT,...* 


SERIALLY REUSABLE: A module with the serially reusable 
attribute can be executed by only one task at a time; that is, a 
task may not begin executing a serially reusable module before a 
previous task has finished executing it. This type of module 
must initialize itself and/or restore any instructions or data 
in the module altered during execution. 


If a module is to be serially reusable, all its control sections 
must be either serially reusable or reenterable. If the 
serially reusable attribute is specified, and any load modules 
that are neither serially reusable nor reenterable become a part 
of the input to the linkage editor, the serially reusable 
attribute is negated. 


To assign the serially reusable attribute, code REUS in the PARM 
field, as follows: 


//\KED EXEC PGM=HEWL,PARM="REUS,...° 


Chapter 4. Specifying JCL to Run a Linkage Editor Job 39 





Refreshable Attribute 


A module with the refreshable attribute can be replaced by a new  - 
copy during execution by a recovery management routine without . 
changing either the sequence or results of processing. This a” 
type of module cannot be modified by itself or by any other 

module during execution. The linkage editor only stores the 

attribute in the directory entry; it does not check whether the 

module is refreshable. 7 


If a module is to be refreshable, all the control sections 
within it must be refreshable. If the refreshable attribute is 
specified, and any load modules that are not refreshable become 
a ol Gia the input to the linkage editor, the attribute is 
negated. | 


To assign the refreshable attribute, code REFR in the PARM 
field, as follows: 


//LKED EXEC PGM=HEWL,PARM='"REFR,...' 


Test Attribute 


A module with the test attribute is to be tested and contains | 
the testing symbol tables for the TSO TEST command. The linkage 
editor accepts these tables as input, and places them in the 
output module. The module is marked as being under test. If 
the test attribute is not specified, the symbol tables are 
ignored by the linkage editor and are not placed in the output 
module. If the test attribute is specified, and no symbol table 
input is received, the output load module will not contain 
symbol tables to be used by the TSO TEST command. 


To assign the test attribute, code TEST in the PARM field, as 
follows: 


//\LKED EXEC PGM=HEWL,PARM='TEST,...'° 


Note: The test attribute applies to programs using either 
TESTRAN or the TSO TEST command. Do not use the ‘TEST’ option 
oe load module is to be executed by either TSO or 


Authorization Code 


The output load module is assigned an authorization code that 
determines whether or not the load module may use restricted 
system services and resources. 


To assign an authorization code through the PARM field, code the 
AC parameter as follows: 


//LKED EXEC PGM=HEWL,PARM="AC=n,...!° 


The authorization code, n, must be 1 to 3 decimal digits with a 
value from 0 to 255. 


"AC=,...' and "AC= * are equivalent to "AC=0'. The 
authorization code assigned in the PARM field is overridden by 
0 oe cece oa en code assigned through the SETCODE control 
statement. 
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Addressing Mode Attribute 


To assign the addressing mode for all the entry points into the 
load module (the main entry point, its true aliases, and all the 
alternate entry points), code the AMODE parameter as follows: 


//LKED EXEC PGM=IEWL, 
PARM=* AMODE=xxx,...!' 





The addressing mode 'xxx' must be either 24, 31, or ANY. 


The addressing mode assigned in the PARM field overrides the 
separate addressing modes found in the ESD data for the control 
sections or private code where the entry points are located. 
The addressing mode assigned in the PARM field is overridden by 
an addressing mode assigned in the MODE control statement. 


If the AMODE parameter occurs more than once in the PARM field 
of the EXEC statement, the last valid parameter is used. 


If only the AMODE value is specified in the PARM field of the 
EXEC statement, an RMODE value of 24 is implied. 


Note: The keyword "AMODE' may also be specified as "AMOD'*. 





Residence Mode Attribute 








To assign the residence mode for the output load module, code 
the RMODE parameter as follows: 


//LKED EXEC PGM=IEWL, 
PARM="RMODE=xxx,...! 


The residence mode 'xxx" must be either 24 or ANY. 


The residence mode assigned in the PARM field overrides the 

| residence mode accumulated from the input control sections and 
private code. The residence mode assigned in the PARM field is 
shel esa by a residence mode assigned through the MODE control 
statement. 


If the RMODE parameter occurs more than once in the PARM field 
of the EXEC statement, the last valid parameter is used. 


If only an RMODE value of ANY is specified in the PARM field of 
the EXEC statement, an AMODE value of 31 is implied. 


If only an RMODE of 24 is specified, no overriding AMODE value 
is assigned; instead, the AMODE value in the ESD data for the 
main entry point, a true alias, or an alternate entry point is 
used in generating its respective directory entry. If any 
control section to be linked has an RMODE=24, then the load 
module is marked RMODE=24. 


Note: The keyword "RMODE® may also be specified as 'RMOD’. 


Combinations of Addressing Mode and Residence Mode 


In generating a directory entry for the main entry point, a true 
alias, or an alternate entry point, the linkage editor validates 
the combination of the AMODE value and the RMODE value, as 
specified by the user in the PARM field of the EXEC statement, 
according to the following table: 


| AMODE=24 jwelid | | 
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Default Attributes 











RMODE=24 | RMODE=ANY 
AMODE=ANY invalid 


If the AMODE/RMODE combination resulting from the PARM field of 
the EXEC statement is invalid, an error message is issued and 
the linkage editor ignores the PARM field of the EXEC statement 
as the source of AMODE/RMODE data. 


Unless specific module attributes are indicated by the 
programmer, the output module is not in an overlay structure, 
and it is not tested. The module is in block format, not 
refreshable, not reenterable, and not serially reusable. If 
page boundary alignment is requested, its control sections are 
aligned on 4K-byte page boundaries. 


One other attribute is specified by the linkage editor after 
processing is finished. If, during processing, severity 2 
errors were found that would prevent the output module from 
being executed successfully, the linkage editor assigns the 
not-executable attribute. The control program will not load a 
module with this attribute. 


If the LET option is specified, the output module is marked 
executable even if severity 2 errors occur. (The LET option is 
discussed later in this section.) 


If the AC parameter is not specified or is coded incorrectly, 
oe authorization code of 0 is assigned to the output | . 
oad module. he ot 


Incompatible Attributes 


Of the module attributes the programmer may specify, several are 
mutually exclusive. When mutually exclusive attributes are 
specified for a load module, the linkage editor ignores the 
less-significant attributes. For example, if both OVLY and RENT 
are specified, the module will be in an overlay structure and 
will not be reenterable. 


Certain attributes ere eiae sncommateole. with other job step 
options. All job step options are shown in Figure 15 on page 52 
along with those options that are incompatible. 


SPECIAL PROCESSING OPTIONS 


The special processing options affect the executability of the 
output module and the use of the automatic library-call 
mechanism. These options are the exclusive call option, the let 
execute option, and the no automatic-call option. 


Exclusive Call Option 


When the exclusive call option is specified, valid exclusive 
references have been made between segments, and the linkage 
editor marks the output module as executable. However, a 

warning message is given for each valid exclusive reference. 


To specify the exclusive call option, code XCAL in the PARM og 
field as follows: | ; (ft 


//LKED EXEC PGM=HEWL,PARM="XCAL,OVLY,...! 
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Let Execute Option 


The OVLY attribute must also be specified for an overlay 
program. 


Note: Unless the let execute option is specified, other errors 
may cause the module to be marked not executable. 


When the let execute option is specified, the linkage editor 
marks the output module as executable even though a severity 2 
error condition was found during processing. (A severity 2 
error condition could make execution of the output load module 
impossible.) Some examples of severity 2 errors are: 

e Unresolved external references 

e Valid or invalid exclusive calls in an overlay program 

e Error on a linkage editor control statement 

e A library module that cannot be found 


e No available space in the directory of the output module 
library 


To specify the let execute option, code LET in the PARM field as 
follows: 


//LKED EXEC PGM=HEWL,PARM="LET,...° 
Note: If LET is specified, XCAL need not be specified. 


No Automatic Library-Call Option 


When the no automatic library-call option is specified, the 
linkage editor library-call mechanism does not call library 
members to resolve external references. The output module is 
marked executable even though unresolved external references are 
present. If this option is specified, the LIBRARY statement 
need not be used to negate the automatic library call for 
selected external references. Also, with this option, a SYSLIB 
DD statement need not be supplied. 


To specify the no automatic library-call option, code NCAL in 
the PARM field, as follows: 


//\LKED EXEC PGM=HEWL,PARM='NCAL,...' 


Note: Unless the LET option is also specified, other errors may 
cause the module to be marked not executable. 


SPACE ALLOCATION OPTIONS 


SIZE Option 


These options allow the programmer to specify the storage 
available to the linkage editor, and to specify the block size 
for the output module. For large modules and SMP, see SMP 
aystem Programmer's Guide; for SMP/E, see / t 


The programmer can specify, through the SIZE option, the amount 
of virtual storage to be used by the linkage editor and the 
portion of that storage to be used as the load module buffer. 


The linkage editor provides default values for the SIZE option. 
The default values are used if one or both of the values are not 
specified correctly by the user or are not specified at all. 
These defaults should be adequate for most link-edits, relieving 
the programmer from specifying the SIZE option for each 
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link-edit. The default values are: yaluel is 256K bytes and 
valueZ is 48K bytes. 


FORMAT: The format of the SIZE option is: 
SIZE=(valuel value?) 
SIZE=(valuel ) 

SIZE=(valuel>» ) 

SIZE=(,value2) 

SIZE=(, ) 


When coded in the PARM field, yvaluel and yvalueZ parameters are 
enclosed in parentheses as follows: 


//LKED EXEC -PGM=HEWL, 
Sf PARM= 'SIZE=(valuel,value2),.. 


Both valuel and value2 may be expressed as integers specifying 
the number of bytes of virtual storage or as nk, where n 
represents the number of IK (©1024) bytes of virtual storage. 


‘ 

iy ‘ 
% if 
i t 


When determining the values for nia SIZE option, it is best to 
establish value2 first, then 


VALUE2: Value2 specifies the number of bytes of storage to be 
allocated as the load module buffer. The allocation specified 
by value2 is a part of the virtual storage specified by 


The actual minimum for value2Z is 6144 (6K) or the length of the 
largest input load module text record, whichever is larger. 

AMBLIST may be used to find the size of the load module text 

records. If a value less than 6144 (6K) is specified, the iy fe 
default value of 48K for value2 is used. : 


The space allocated by yalue2 is used for: the buffer into which 
the input load module text is read, the buffer from which load 
module text is written to the intermediate data set, the buffer 
into which the load module text is read from the intermediate 
data set, and the buffers from which the load module text is 
written to the output data set. Therefore, the determination of 

requires that the programmer consider the record sizes of 
the data sets from which any load module text records are to be 
read (CSYSLIB, any data set referenced by an INCLUDE, any library 
data set), the record size for the intermediate data set 
CSYSUT1), and the record size for the output load module data 
set (SYSLMOD). 


Figure 135 on page 45 lists the direct access devices that may 
contain data sets that are the source of input load module text, 
the intermediate data set, and the output load module data set, 
and lists the maximum record size used for each device by the 
linkage editor. These maximum record sizes may always be used 
in specifying value2 or, if the programmer can determine them, 
exact sizes can be used. 


em 
a 
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Device Maximum SYSUT1 or SYSLMOD 


vice saan — 
2305-2 14660 | 14 

3330-1 13030 12 

3330-11 13030 4p 

3340 8368 

3344 8368 

3350 19069 18 

3375 32760 18 

3380 32760 18 


Figure 13. SYSUT1 and SYSLMOD Device Types and Their Maximum 
Record Sizes 


The programmer must specify value2 so that the linkage editor 
has sufficient space to allocate buffers that are compatible 
with the record sizes for the intermediate data set and the 
output load module data set. 


The linkage editor optimizes the record size for the device type 
of output load module data set unless one of the following 
conditions exists. 


1. The programmer has specified PARM="...DCBS,...', and the 
SYSLMOD DD statement contains a BLKSIZE subparaneter in the 
DCB parameter, forcing the linkage editor to write records 
having a maximum length equal to the BLKSIZE specification. 


2. The output load module data set is an existing data set 
having a block size less than the optimum record size, 
forcing the linkage editor to write records no longer than 
that block size. 


3. The programmer has specified a valueZ less than twice the 
maximum record size for the output load module data set, 
forcing the linkage editor to write records having a maximum 
size of one-half value2. 


4. The intermediate data set and the output load module data 
set have dissimilar record sizes, forcing the linkage editor 
to write records having a maximum size determined for 
compatibility between the two data sets. 


The linkage editor optimizes the record size of the output load 
module data set for its device type but selects a record size 
compatible with the intermediate data set (see restrictions 
above). Therefore, if the intermediate data set and the output 
load module data set reside on the same device type, use of the 
load module buffer is optimized. Also, if the data sets are on 
different units of the same type, the performance of the linkage 
editor is improved. 


Figure 14 on page 46 shows the record sizes used for 


compatibility between every combination of device types for the 
intermediate and output load module data sets. 
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SYSLMOD Record Size SYSUT1 Record Size 


Maximum Maximum 

Record Record 
Device Size Device Size 
Used Produced Used Produced 


IBM 2305-2 14K 2305-2 14K 
12K3 3330,3330-11 12K 
12K? 33 6K 

14K 3350,3575,5380 14K2 


3330 12K 2505-2 





3330-11 12K 3330,33550-11 
12K 3340 
12K 3350,3375,33580 


3340 7K 2505-2 
3344 6K 3330,3330-11 
8K 3340 
3350,3375,3380 
3350 14K} 2305-2 
3375/3380 3330,3350-11 
1 3340 
3350,3375,35380 





Figure 14. Load Module Buffer Area and SYSLMOD and SYSUTI 
Record Sizes 


Notes to Figure 14: 


1 The SYSLMOD record size is reduced to less than the maximum 


to make it compatible with the SYSUT1 record size. ae 
2 The SYSUT1 record size is reduced to less than the maximum to 
to make it compatible with the SYSLMOD record size. 
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Value2 should be, minimally, twice the record size for the 
output load module data set. If yvalue2 can be made larger than 
twice the record size for the output load module data set, the 
increase should be the larger of the record sizes for the 
intermediate and output load module data sets. 





The practical maximum for value2 is the length of the load 
module to be built, plus GK bytes if the length of the load 
module to be built is equal to or greater than 40960 (40K). Any 
space allocated to the load module buffer above this amount is 
not used and does not need be allocated to ; 


If a value2 is specified that cannot be accommodated in the 
available storage, value2Z is reduced to the next lower 2K-byte 
multiple of storage that is available. This reduction, however, 
never decreases yalue2 to less than the minimum, 61449 (6K). 


The optimal value2 is the practical maximum, as explained above. 
If the entire load module is contained in storage, the 
performance of the linkage editor is improved and the use of the 
intermediate data set may be eliminated. 


Examples of Value2 Determination 


1. <A load module of between 21K and 22K bytes is to be built. 
The load module data set is a new data set on an IBM 3330 
Disk Storage device. The intermediate data set is allocated 
to an IBM 3340 Direct Access Storage device. A SYSLIB data 
set is to be used, residing on a 3330. The entire load 
module could be contained in the load module buffer if 
were 22K bytes (the load module size). The practical 
minimum for yvalue2 would be 12K bytes (the size of the 
largest possible input load module text record from the 
SYSLIB data set). However, value2Z should be at least as 
large as two records to be written to the load module data 
_ set (that is, 24K bytes). There is a reconciliation 
—— necessary in this case between the two dissimilar device 
f | types for the intermediate and output load module data sets; 
: but the record size of the output load module data set is an 
even multiple of the record size of the intermediate data 
set so no adjustment of the record sizes is made. 
Therefore, the practical minimum, as well as the practical 
maximum and optimal value2 in this case is 24K bytes. 


2. A load module of more than 50K bytes is to be relink-edited; 
however, a maximum of 40K bytes is available to be allocated 
to yalueZzg. The output load module data set is an old data 
set residing on a 3340, written with maximum record size. 
The intermediate data set is allocated to an IBM 2305-2 
Fixed Head Storage device. The link-edit involves a control 
section in the SYSLIN data set that will replace a control 
section in the old load module, followed by an INCLUDE 
statement naming the old load module on the SYSLMOD data 
set. The maximum for value2 cannot be satisfied, since only 
GOK bytes is available. The size of two maximum records 
written to a 3340 would be 14K bytes. However, the size of 
one record to be written or to be read from the intermediate 
data set is 14K bytes. Therefore, the minimum for value2Z in 
this case is 14K bytes. This is sufficient space for one 
input load module text record or one record written to or to 
be read from the intermediate data set or two records 
written to the output load module data set. 


3. The output load module data set resides on a 2305-2. The 
intermediate data set is allocated to a 3330. All load 
module input comes from a 3330. Value2 in this case is 24K 
bytes, because the input load module text records are, at 
most, 12K bytes, the records written to and read from the 
intermediate data set are 12K bytes, and the records written 
to the output load module data set are 12K bytes. The 


_ maximum record size of 14K bytes for the 2305-2 is reduced 
( ; to 12K bytes for this link-edit in order to be compatible 
bes” with the intermediate data set. 
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An alternative for value2 in the above example is 12K bytes. 

This 12K bytes is adequate for the input load module text 

records and the records written to and read from the 

intermediate data set. The 12K value forces a maximum —— 

record size of 6K bytes to be written to the output load Wee” 
module data set. At 6K bytes each, two records can be 

written on a 2305-2 track while, as in the above example, 

one record of 12K bytes can be written on a 2305-2 

rack. 





G4. The output load module data set is a new data set allocated 
to a 3330. The programmer has specified the linkage editor 
parameter DCBS, and the SYSLMOD DD statement contains 
"...DCB=(€...BLKSIZE=3072,...),...'. The only load module 
input comes from a data set created previously in a similar 
manner. The intermediate data set is allocated to a 3340. 
The minimum for value2 in this case is 6K bytes; the input 
load module records are 3K bytes at most, the intermediate 
data set records are 7K bytes at most, and, as directed by 
the programmer, the linkage editor produces records having a 
maximum size of 3K bytes on the output load module data set. 


VALUE]: Valuel specifies the number of bytes of virtual storage 
available to the linkage editor regardless of the private area 
Size. The storage specified by valuel includes the allocation 
specified by yvalue2d. 


The absolute minimum for yalue]l is the design point of the 
linkage editor, 96K bytes. If a value less than the minimum for 
value] is specified, the default options for both yaluel and 
value2 are used. 


The practical minimum for yvaluel is 98304 (96K) bytes plus any 
excess in value2 over 6144 (6K) bytes, plus any additional space 
required to support the blocking factor for the SYSLIN, object 
module library, and SYSPRINT data sets. 


The design point of the linkage editor provides for the minimum ; 
load module buffer-——6144 (6K) bytes of virtual storage. Ifa Se? 
load module buffer larger than 6194 (6K) bytes is specified in 
value2, valuel must be increased by the excess of that yvalue2 
over 6144 (6K) bytes. 


The linkage editor supports three different blocking factors for 
the SYSLIN, object module library, and SYSPRINT data sets; they 
are 5, 10, and 40 to 1. The requirement for additional space 
depends upon the blocking factor that is to be supported. 


The following table shows the additional space required to 
support each blocking factor. 


Blocking Space 
Factor Required 


10 to l 18432 or 18K 
40 to 1 28672 or 28K 





Blocking factors of 1 through 4%, 6 through 9, and 11 through 39 
are treated as blocking factors of 5, 10, and 40, respectively. 
Blocking factors greater than 40 are invalid. 


The additional space requirement is determined by the largest 
blocking factor among the affected data sets. 


The blocking factor supported is dependent upon space available fo 
after value2 has been allocated to the load module buffer out of C ; 
Therefore, if the space provided in valuel is ae 


insufficient, the next smallest blocking factor is used. 
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DCBS Option 








The performance of the linkage editor can be improved by the 
allocation of additional storage by yvyaluel, especially in 
providing for the optimal valued. 


The maximum value that can be specified for yaluel is 9999999 or 
9999K. However, the amount of virtual storage actually 
allocated for yaluel is the smaller of: 


e The region size 
® The amount specified for valuel 
Examples of Valuel Determination 


1. Assume that an optimum value2 of 36K bytes has already been 
determined for the link-edit. An appropriate yalue] is 126K 
bytes, because an additional 30K bytes, above the minimum of 
96K bytes, is needed to support the allocation of 36K bytes 
to value2 and no additional storage is required to support 
the blocking factors for SYSLIN, SYSPRINT, and any object 
module libraries. 


2. The minimum for value2 (6K bytes) is used. All the object 
module libraries are blocked 5-to-l, except one that is 
blocked 10-to-l1. The SYSLIN and SYSPRINT data sets are 
assigned blocking factors of 5. An appropriate valuel for 
this link-edit is 114K bytes, the minimum plus the 18K betes 
needed to support the blocking factor of 10-to-l on the 
object module library. 


The DCBS option allows the programmer to specify the block size 
age eee data set in the DCB parameter of SYSLMOD DD 
statemen 


If the DCBS option is specified, the block size value in the 

DSCB for the SYSLMOD data set may be overridden. If the DCBS 
option is not specified, the block size value in the DSCB for 
the SYSLMOD data set may not be overridden. 


If the DCBS option is specified and no block size value is 
provided in the DCB parameter of the SYSLMOD DD statement, the 
linkage editor uses the maximum record size for the device. If 
the DCBS option is not specified and a block size value is 
provided in the DCB parameter of the SYSLMOD DD statement, the 
block size value in the DCB parameter of the SYSLMOD DD 
statement is ignored by the linkage editor. 


Even though the DCBS option is specified, the linkage editor 
will not allow the programmer to set the block size for the 
SYSLMOD data set to a value less than the minimum; that is, 256, 
or 1024 if the SCTR option is specified, or a value less than 
the block size in the DSCB for an existing data set. 


The block size specified by the programmer will be used unless 
€1) it is larger than the maximum record size for the device, in 
which case the maximum record size is used, or (2) it is less 
than the minimum block size, in which case the minimum block 
Size is used. 
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OUTPUT OPTIONS 


The following example shows the use of the DCBS option for an 
IBM 33550 Direct Access Storage device: 


//LKED EXEC PGM=HEWL,PARM=*XREF, DCBS* 


//SYSLMOD DD DSNAME=LOADMODC( TEST), DISP=(NEW, KEEP), 
17 DCB=(BLKSIZE=3072),... 





As a result, the linkage editor uses a 3K-byte block size for 
the output module library. 


These options control the optional diagnostic output produced by 
the linkage editor. The programmer can request that the linkage 
editor produce a list of all control statements and a module map 
or cross-reference table to help in testing a program. The 
format of each is described in "Chapter 8. Interpreting Linkage 
Editor Output™ on page 107. 


In addition, the programmer can request that the numbered 
error/warning messages generated by the linkage editor appear on 
the SYSTERM data set as well as on the SYSPRINT data set. 


Control Statement Listing Option 


Module Map Option 


To request a control statement listing, code LIST in the PARM 
field, as follows: 


7/LKED EXEC PGM=HEWL,PARM='"LIST,...° 
When the LIST option is specified, all control statements 


processed by the linkage editor are listed in card-image format 
on the diagnostic output data set. 


To request a module map, code MAP in the PARM field, as follows: 
//\LKED EXEC PGM=HEWL,PARM="MAP,...° 
When the MAP option is specified, the linkage editor produces a 


ecoue map of the output module on the diagnostic output data 
set. 


Cross Reference Table Option 


To request a cross-reference table, code XREF in the PARM field, 
es follows: 


//LKED EXEC  PGM=HEWL,PARM='XREF,...° 


When the XREF option is specified, the linkage editor produces a 
cross-reference table of the output module on the diagnostic 
output data set. The cross-reference table includes a module 
map; therefore, both XREF and MAP need not be specified for one 
linkage editor job step. 
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Alternate Output (SYSTERM) Option 


To request that the numbered linkage editor error/warning 
messages be generated on the data set defined by a SYSTERM DD 
statement, code TERM in the PARM field, as follows: 


/7LKED EXEC PGM=HEWL,PARM='TERM,...' 


When the TERM option is specified, a SYSTERM DD statement must 
be provided. If it is not, the TERM option is negated. 


Output specified by the TERM option supplements printed 
diagnostic information; when TERM is used, linkage editor 
error/warning messages appear in both output data sets. 


INCOMPATIBLE JOB STEP OPTIONS 





When mutually exclusive job step options are specified for a 
linkage editor execution, the linkage editor ignores the less 
Significant options. Figure 15 on page 52 illustrates the 
Significance of those options that are incompatible. When an X 
appears at an intersection, the options are incompatible. The 
option that appears higher in the list is selected. 
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Figure 15. Incompatible Job Step Options for the Linkage Editor 
For example, to check the compatibility of XREF and NE, follow 
the XREF column down and the NE row across until they intersect. 
Because an X appears where they intersect, they are 
incompatible; XREF is selected; NE is negated. 
If incorrect values are specified for the SIZE parameter, the 
default values are used. If incompatible options are detected, 
the message 
*¥* OPTIONS INCOMPATIBLE xx 
is printed. This message follows the standard module 
disposition message. 
If the incompatible options OVLY and AMODE or RMODE are 
specified, a diagnostic message is issued. 

% 
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EXEC STATEMENT~~REGION PARAMETER 


dae The REGION parameter specifies the maximum amount of storage 
( that can be allocated to satisfy a request for storage that the 
linkage editor makes. In its minimal situation, the linkage 
editor requires a REGION parameter of not less than 96K bytes; 
in its default situation, not less than 256K bytes; and, in its 
maximal situation (see "Size Parameter Guidelines" on page 60), 
not less than 1500K bytes. 


EXEC STATEMENT—-RETURN CODE 


The linkage editor passes a return code to the control program 
upon completion of the job step. The return code reflects the 
highest severity code recorded in any iteration of the linkage 
editor within that job step. The highest severity code 
encountered during processing is multiplied by 4 to create the 
return code; this code is placed into register 15 at the end of 
linkage editor processing. Figure 16 contains the return codes, 
the corresponding severity code, and a description of each. 





Return Severity 


Code Code Description 
00 0 Normal conclusion 
04 1 Warning messages have been listed; execution 








should be successful. For example, if the 
overlay option is specified and the overlay 
structure contains only one segment, a 
return code of 04 is placed in register 15. 


08 2 Error messages have been listed; execution 
ee may fail. The module is marked not executable 
( unless the LET option is specified. For 
example, if the block size of a specified 
library data set cannot be handled by the 
linkage editor, a return code of 08 is placed 
in register 15. 


oc 3 Severe errors have occurred; execution is 
impossible. For example, if an invalid entry 
point has been specified, a return code of O0C 
is placed in register 15. 


10 q Terminal errors have occurred; the 
processing has terminated. For example, if 
the linkage editor cannot handle the blocking 
factor requested for SYSPRINT, a return code 
of 10 is placed in register 15. 


Figure 16. Linkage Editor Return Codes 


The programmer may use a return code to determine whether or not 
the load module is to be executed by using the condition 
parameter CCOND) on the EXEC statement for the load module. The 
control program compares the return code with the values 
specified in the COND parameter, and the results of the 
comparisons are used to determine subsequent action. The COND 
parameter may be specified either in the JOB statement or the 
EXEC statement (see the publication JCL). 
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DD STATEMENTS 





Every data set used by the linkage editor must be described with 
a DD statement. Each DD statement must have a name, unless data 
sets are concatenated. The DD statements for data sets required 
by the linkage editor have preassigned names; those for 
additional input data sets have user-assigned names; those for 
concatenated data sets Cafter the first) have no names. 


In addition to the name, the DD statement provides the control 
program with information about the input/output device on which 
the data set resides, and a description of the data set itself. 
All of the job control language facilities for device 
description are available to the users of the linkage editor. 


Besides information about the device, the DD statement also 
contains a data set description which includes the data set name 
and its disposition. Information for the data control block 
(DCB) may also be given. , 


General information pertinent to the linkage editor on the data 
set name and DCB information follows; information on disposition 
is given in the discussion for each data set. 


DATA SET NAME: The linkage editor uses either sequential or 
partitioned data sets. For sequential data sets, only the name 
of the data set is specified; for partitioned data sets, the 
member name must also be specified either on the DD statement or 
with a control statement. 


When input data sets are passed from a previous job step, or 
when the output load module is being tested, a recommended 
practice is to use temporary data set names (that is, &&dsname). 
Use of temporary names ensures that there are no duplicate data 
sets with out-of-date modules. A data set with a temporary name 
is automatically deleted at the end of the job. When a module 
is to he stored permanently, a data set name without ampersands 
is used. 


DCB INFORMATION: Before a data set can be used for input, 
information describing the data set must be placed in the data 
control block (DCB). If this information does not exist in the 
DCB or header label, or if no labels are used (magnetic tape 
does not require labels), the programmer must specify it in the 
DCB parameter on the DD statement. 


Record format CRECFM), logical record size CLRECL), and block 
size (BLKSIZE) subparameters of the DCB parameter are discussed 
as they apply to the linkage editor. Specific information on 
each as it applies to the linkage editor data sets is given in 
the description of the data set later in this section. Other 
DCB information (tape recording technique, density, and so 
forth) is described in the publication JCL 


Record Format: The following record formats are used with the 
linkage editor: 


F The records are fixed length. 

FB The records are fixed length and blocked. 

FBA The records are fixed length, blocked, and contain 
American National Standards Institute CANSI) control 
characters. 

FBS The records are fixed length, blocked, and written in 
standard blocks. 

FA The records are fixed length and contain ANSI control 
characters. 

FS The records are fixed length and written in standard 
blocks. 
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U The records are undefined length. 


ae UA The records are undefined length and contain ANSI 
7 control characters. 


A record format of FS or FBS must be used with caution. All 
blocks in the data set must be the same size. This size must be 
equal to the specified block size. A truncated block can occur 
only as the last block in the data set. 


Note: Track overflow is never used by the linkage editor. When 
moving or copying load modules, it is recommended that the track 
overflow feature not be used on the target data set, as errors 
may occur in fetching the load modules for execution. 


LOGICAL RECORD AND BLOCK SIZE: Blocking is allowed for input 
object module data sets and the diagnostic output data set. The 
blocking factors used to determine buffer allocations are 5, 10, 
and 40. The BLKSIZE must therefore be a multiple of LRECL. See 
the description of blocking factors in the discussion of the 
SIZE option. 





When the DCBS option is specified, a block size should be 
specified for the output load module library (see "SYSLMOD DD 
Statement™ on page 57). 


LINKAGE EDITOR DD STATEMENTS 





The linkage editor uses six data sets; of these, four are 
required. The DD statements for these data sets must use the 
preassigned ddnames given in Figure 17. The descriptions that 
follow give pertinent device and data set information for each 
linkage editor data set. 


Data Set Required 
Primary input data set SYSLIN 


Automatic call library SYSLIB Only if the 
automatic library 
call mechanism is 
used 


Intermediate data set SYSUT1 
Diagnostic output data set SYSPRINT 
Output module library SYSLMOD 


Alternate output data set SYSTERM Only if the TERM 
option is specified 


Figure 17. Linkage Editor ddnames 



















SYSLIN DD Statement 


The SYSLIN DD statement is always required; it describes the 
primary input data set that can be assigned to a direct access 
device, a magnetic tape unit, or the card reader. The data set 
may be either sequential or partitioned; in the latter case, a 
member name must be specified. 


If SYSLIN is assigned to a card reader or "pseudo card reader," 
input records must be unblocked and 80 bytes long. CA pseudo 
card reader is defined as input from a tape or a direct access 
device in card reader mode. ) 
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SYSLIB DD Statement 


SYSUT1 DD Statement 


This data set must contain object modules and/or control 
statements. Load modules used in the primary input data set are 


considered a severity 4 error. —_ 
The recommended disposition for the primary input data set is oe 
SHR or OLD. 


The DCB requirements are shown in Figure 18. 


DCB Requirements 


LRECL BLKSIZE RECFM 
80 80 F,FS 
80 400,800,32002 FB,FBS 


These are the maximum block sizes allowed for each of the 
optimal blocking factors (5, 10, and 40). Which maximum is 
applicable depends on the value given to valuel and value2 of 
the SIZE option. 


Figure 18. DCB Requirements for Object Module and Control 
Statement Input 


The SYSLIB DD statement is required when the automatic 
library-call mechanism is to be used. This DD statement 
describes the automatic call library, which must be assigned to | | 
a direct access device. The data set must be partitioned, but cy 
member names should not be specified. ia 


The recommended disposition for the call library is SHR or OLD. 


If concatenated call libraries are used, object and:load module 
libraries must not be mixed. If only object modules are used, 
the call library may also contain control statements. 


The DCB requirements for object module call libraries are given 
in Figure 18. The DCB requirement for load module call 

lib: aries is a record format of U; the block size used for 
storage allocation is equal to the maximum for the device used, 
not the record read. Note that the linkage editor recognizes 
object and load module call libraries solely from their record 
format, and not from the data within them. 


This data set must not be assigned to SYSOQUT. 


The SYSUT1 DD statement is always required; it describes the 
intermediate data set, which is a sequential data set assigned 
to a direct access device. Space must be allocated for this 
mat set, but the DCB requirements are supplied by the linkage 
editor. 7 
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SYSPRINT DD Statement 


The SYSPRINT DD statement is always required; it describes the 
diagnostic output data set, which is a sequential data set 
assigned to a printer or to an intermediate storage device. If . 
an intermediate storage device is used, the data records contain 
a carriage control character as the first byte. 


The usual specification for this data set is SYSOUT=A. The 
programmer may assign a block size. The record format assigned 
a linkage editor depends on whether blocking is used or 
not. 


Figure 19 shows the DCB requirements for SYSPRINT. The only 
information that can be supplied by the programmer is the block 
size. 





DCB Requirements for SYSPRINT 








LRECL BLKSIZE RECFM 
12l 121 FA 
121 n x 121 where n FBA 
is less than or 
equal to 40 


Note: The value specified for BLKSIZE, either on the DCB 
parameter of the SYSPRINT DD statement or in the DSCB (data set 
control block) of an existing data set, must be a multiple of 
121; if it is not, the linkage editor issues a message to the 
operator's console and terminates processing. 


Figure 19. DCB Requirements for SYSPRINT 


SYSLMOD DD Statement 


The SYSLMOD DD statement is always required; it describes the 
output module library, which must be a partitioned data set 
assigned to a direct access device. 


A member name may be specified on the SYSLMOD DD statement. If 
a member name is specified, it is used only if a name was not 
specified on a NAME control statement. This member name must 
conform to the rules for the name on the NAME control statement. 
This would imply the replacement of an identically named member 
in the output load module library, if one exists. 


If SYSLMOD is to be referenced by an INCLUDE statement, the 
member name on the DD statement, if present, must be the name of 
an existing member. 


If the member is to replace an identically named member in an 
existing library, the disposition should be OLD or SHR. If the 
member is to be added to an existing library, the disposition 
should be MOD, OLD, or SHR. If no library exists and the member 
is the first to be added to a new library, the disposition 
should be NEW or MOD. If the member is to be added to an 
existing library that may be used concurrently in another region 
or partition, the disposition should be SHR. 


The record format U is assigned by the linkage editor. See 
"Appendix D. Loader Storage Considerations” on page 190. 
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Procedures used by the linkage editor to assign block size are: 
1. If the data set is new: | —_ 
a. Without the DCBS option specified: 

e The DSCB (data set control block) reflects the 
maximum block size available for the device type if 
it is not restricted by value2 of the size 
parameter. 

e If SCTR is specified, the block size is 1024. 


b. With the DCBS option specified, the DSCB block size is 
the smaller of: 





® The maximum track size for the device. 


® The value of the BLKSIZE subparameter on the DCB 
parameter of the SYSLMOD DD statement. 


e The actual output eg length Chalf the number 
specified for value2g if the size option was 
utilized). 


c. The minimum DSCB block size is 256 without the SCTR 
option specified and 1024 with the SCTR option. 


2. When the DSCB block size already exists (not a new data set 
and the SCTR option is specified, 1024 is used. 


3. When the DSCB block size already exists and the DCBS or SCTR 
option is not specified, the larger of the existing block 
Sizes or 256 is used. 


4. See "DCBS Option" on page 49 for the procedure when the DSCB 
block size exists and the DCBS option is specified. 


Note: When a new data set is created at linkage editor time 
without the DCBS option specified, the DSCB reflects the maximum 
block size available for the device type. 


If the SYSLMOD DD statement is used as a source of load module 
Gee the SYSLMOD data set is read with a record format of U in 
a cases. 


In the following example, the SYSLMOD DD statement specifies a 
permanent library on an IBM 3350 Disk Storage Device: 


//SYSLMOD DD DSNAME=USERLIBCTAXES), DISP=MOD, 
7 UNIT=3350,... 


The linkage editor assigns a record format of U, and a logical 


record and block size of 18K bytes, the maximum for a 3350 
However, consider the following example: 


//\LKED EXEC  PGM=HEWL,PARM='XREF,DCBS* 


//SYSLMOD DD DSNAME=USERLIBCTAXES) , DISP=MOD, 
1 UNIT=3340, DCB=(BLKSIZE=3072),... 





The linkage editor still assigns a record format of U, but the 
logical record and block size are now 3K bytes rather than 7K 
bytes, because of the use of the DCBS option. 
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' SYSTERM DD Statement 


The SYSTERM DD statement is optional; it describes a data set 
that is used only for numbered error/warning messages. Although 
intended to define the terminal data set when the linkage editor 
is being used under the Time Sharing Option (TSO) of MVS, the 
SYSTERM DD statement can be used in any environment to define a 
data set consisting of numbered error/warning messages that 
supplements the SYSPRINT data set. 


SYSTERM output is defined by including a SYSTERM DD statement 
and specifying TERM in the PARM field of the EXEC statement. 
When SYSTERM output is defined, numbered messages are then 
written to both the SYSTERM and SYSPRINT data sets. 


The following example shows how the SYSTERM DD statement could 
be used to specify the system output unit: 


//SYSTERM DD SYSOUT=A 


The DCB requirements for SYSTERM CLRECL=121,BLKSIZE=121, and 
RECFM=FBA) are supplied by the linkage editor. If necessary, 
the linkage editor will modify the DSCB Cdata set. control block) 
of an existing data set to reflect these values. 





ADDITIONAL DD STATEMENTS 


Each ddname specified on an INCLUDE or a LIBRARY control 
statement must also be described with a DD statement. These DD 
statements describe sequential or partitioned data sets, 
assigned to magnetic tape units or direct access devices (not 
pseudo card readers). 











The ddnames are specified by the user with any other necessary 
( pecans The DCB requirements for these data sets are shown 
in Figure 20. 


LRECL BLKSIZE RECFM 


Object modules and/or 80 80 F,FS 
| control statements 80 400,800,32001 FS,FBS 


Load modules Ignored Maximum U 
for device, 
or one-half 
Of value2, 
whichever 
is smaller 


Figure 20. DCB Requirements for Data Sets Used by Include and 
Library Control Statements 


Note to Figure 20: 


1 These are the maximum block sizes allowed for each of the 
optimal blocking factors (5, 10, 40). Which maximum is 
applicable depends on the values given to yaluel and 
of the SIZE option. 


When concatenated data sets are included, each data set must 
contain records of the same format, record size, and block size. 
If the data sets reside on magnetic tape, the tape recording 
technique and density must also be identical. 


( If the SYSLMOD DD statement is used as a source of load module 


input, the SYSLMOD data set is read with a record format of U in 
all cases. 
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SIZE PARAMETER GUIDELINES 


This section gives guidelines for determining appropriate SIZE ef 4 
| parameter values for a linkage editor job step. ea 7 
| First—determine Value2 of the SIZE parameter. 
Value2=(6K16144|flg|Catb) | Coxd) | Ccxe) ] 
where: 
a is the length of the load module to be built. 
b is 0, if the length of the load module to be built is < 
40K bytes. 
is 4K, if the length of the load module to be built is 2 
| GOK bytes. 
| c is an integer equal to or greater than 2, such that cxd 
or cxe is S$ 999999 or 9999K bytes (c is the integer that 
represents the number of buffers to be reserved for 
SYSLMOD). | 
d is the track capacity of the SYSLMOD device, or 18K 
whichever is larger. 
e is the block size of the SYSLMOD data set. 
is the length of the largest text record in load module 
input. 
g is the track capacity of the SYSUT1 device, or 18K 
whichever is larger. 
Selecting the largest of the above parameters provides optimal ere 
results. ‘ : 
ae 


Second—determine Value] of the SIZE parameter. 
Valuel = h+jtk 
Valuel must range between h and 9999K or 9999999 


where: 

h = 96K 

5 is the excess of Value2 over 6K 

k is the additional storage required to support the 
eyconins for SYSLIN, object module libraries, and 








5 to l 


Blocking Factor K (Bytes) 


Third—determine the REGION parameter. 
REGION = Equal to or greater than Valuel 
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LINKAGE EDITOR CATALOGED PROCEDURES 


Procedure LKED 








To facilitate the operation of the system, the control program 
allows the programmer to store EXEC and DD statements under a 
unique member name in a procedure library. Such a series of job 
control language statements is called a 

These job control language statements can be re-called at any 
time to specify the requirements for a job. To request this 
procedure, the programmer places an EXEC statement in the input 
stream. This EXEC statement specifies the unique member name of 
the procedure desired. 


The specifications in a cataloged procedure can be temporarily 
overridden, and DD statements can be added. The information 
altered by the programmer is in effect only for the duration of 
the job step; the cataloged procedures themselves are not 
altered permanently. Any additional DD statements supplied by 
the pieaeonner must follow those that override the cataloged 
procedure. 





Two linkage editor cataloged procedures are provided: a 
single-step procedure that link-edits the input and produces a 
load module (procedure LKED), and a two-step procedure that 
link-edits the input, produces a load module, and executes that 
module (procedure LKEDG). Many of the cataloged procedures 
provided for language translators also contain linkage editor 
steps. The EXEC and DD statement specifications in these steps 
are similar to the specifications in the cataloged procedures 
described in the following paragraphs. 





The cataloged procedure named LKED is a single-step procedure 
that link-edits the input, produces a load module, and passes 
the load module to another step in the same job. The statements 
in this procedure are shown in Figure 21; the following text 
describes these statements. | 


//LKED EXEC PGM=HEWL,PARM='XREF,LIST,LET,NCAL*,REGION=96K 
Z/SYSPRINT DD SYSOUT=A 

//SYSLIN DD DDNAME=SYSIN 

/7SYSLMOD DD DSNAME=&&GOSET (GO), SPACE=(€1024, €50,20,1)), 

// UNIT=SYSDA, DISP=CMOD, PASS) 

//SYSUTI DD UNIT=CSYSDA,SEP=CSYSLMOD, SYSLIN)), 

// SPACE=(1024, €200,20)) 


Figure 21. Statements in the LKED Cataloged Procedure 


STATEMENT NUMBERS: The 8-digit numbers on the right side of 
each statement (not shown in Figure 21) are used to identify 
each statement and would be used, for example, when permanently 
modifying the cataloged procedure with the system utility 
program IEBUPDTE. For a description of this utility program, 
see Utilities. 


EXEC STATEMENT: The PARM field specifies the XREF, LIST, LET, 
and NCAL options. If the automatic library-call mechanism is to 
be used, the NCAL option must be overridden, and a SYSLIB DD 
statement must be added. Overriding and adding DD statements is 
discussed later in this section. 
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SYSPRINT STATEMENT: The SYSPRINT DD statement specifies the 
SYSOUT class A, which is either a printer or an intermediate 
storage device. If an intermediate storage device is used, 
American National Standard Institute control characters 
accompany the data to be printed. 


SYSLIN STATEMENT: The specification of DDNAME=SYSIN allows the 
Programmer to specify any input data set as long as it fulfills 
the requirements for linkage editor input. The input data set 
must be defined with a DD statement with the ddname SYSIN. This 
data set may be either in the input stream or reside ona 
separate volume. 


If the data set is in the input stream, the following SYSIN 
statement is used: 


7/LKED.SYSIN DD % 


If this SYSIN statement is used, it may be anywhere in the job 
step DD statements as long as it follows all overriding DD 
statements. The object module decks and/or control statements 
should follow the SYSIN statement, with a delimiter statement 
(7%) at the end of the input. 


If the data set resides on a separate volume, the following 
SYSIN statement is used: 


//LKED.SYSIN DD (parameters describing the input data set) 


If this SYSIN statement is used, it may be anywhere in the job 
step DD statements as long as it follows all overriding DD 
statements. Several data sets may be concatenated, as described 
in Ss oee te. 3. Defining Input to the Linkage Editor" on 

page ‘ 


SYSLMOD STATEMENT: The SYSLMOD DD statement specifies a 
temporary data set and a general space allocation. The 
disposition allows the next job step to execute the load module. 
If the load module is to reside permanently ina library, these 
general specifications must be overridden. 


SYSUT1 STATEMENT: The SYSUT1 DD statement specifies that the 
intermediate data set is to reside on a direct access device, 
but not the same device as either the SYSLMOD or the SYSLIN data 
sets. Again, a general space allocation is given. 


SYSLIB STATEMENT: Note that there is no SYSLIB DD statement. 
If the automatic library-call mechanism is to be used with a 
cataloged procedure, a SYSLIB DD statement must be added; also, 
the Ais option in the PARM field of the EXEC statement must be 
negated. 


INVOKING THE LKED PROCEDURE: To invoke the LKED procedure, code 
the following EXEC statement: 


//stepname EXEC LKED 

where stepname is optional and is the name of the job step. 

The following example shows a sample JCL sequence for using the 
LKED procedure in one step to link-edit object modules to 


produce a load module, then execute the load module in a 
subsequent step. 
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Procedure LKEDG 


//LESTEP EXEC  LKED 

(Overriding and additional DD statements for the LKED step) 
//7LKED.SYSIN DD ¥ 

(Object module decks and/or control statements) 
/7EXSTEP EXEC PGM=%.LESTEP.LKED.SYSLMOD 


(DD statements and data for load module execution) 


/% CIf data is supplied for the execution step) 





Note: LESTEP invokes the LKED procedure and EXSTEP executes the 
load module produced by LESTEP. 


The cataloged procedure named LKEDG is a two-step procedure that 
link-edits the input, produces a load module, and executes that 
load module. The statements in this procedure are shown in 
Figure 22. The two steps are named LKED and GO. The 
specifications in the statements in the LKED step are identical 
to the specifications in the LKED procedure. 


//7\LKED EXEC PGM=HEWL,PARM="XREF,LIST,NCAL',REGION=96K 
//SYSPRINT DD SYSOUT=A | 

//SYSLIN DD DDNAME=SYSIN 

7/7SYSULMOD DD DSNAME=&&GOSET (GO) , SPACE=(1024, €50,20,1)), 
17 UNIT=CSYSDA, DISP=CMOD, PASS) 

f/SYSUTI DD UNIT=CSYSDA, SEP=CSYSLMOD,SYSLIN)D), 

17 SPACE=(1024, (200, 20)) 

47G0 EXEC PGM=*.LKED.SYSLMOD,COND=(4,LT,LKED) 


Figure 22. Statements in the LKEDG Cataloged Procedure 


GO STEP: The EXEC statement specifies that the program to be 
executed is the load module produced in the LKED step of this 
j30b. This module was stored in the data set described on the 
SYSLMOD DD statement in that step. CIf a NAME statement was 
used to specify a member name other than that used on the 
SYSLMOD statement, use the LKED procedure. ) 


The condition parameter specifies that the execution step is to 
be bypassed if the return code issued by the LKED step is 
greater than 4. 


INVOKING THE LKEDG PROCEDURE: To invoke the LKEDG procedure, 
code the following EXEC statement: 


//stepname EXEC LKEDG 
where stepname is optional and is the name of the job step. 
The following example shows a sample JCL sequence for using the 


LKEDG procedure to link-edit object modules, produce a load 
module, and execute that Load module. 
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//TWOSTEP =§ EXEC  LKEDG. 


(Overriding and additional DD statements for the LKED step) 
//LKED.SYSIN DD % 


(Object module decks and/or control statements) 


7% 
(DD statements for the GO step) 
//G0.SYSIN DD % 


(Data for the GO step) 
/% 





OVERRIDING CATALOGED PROCEDURES 


Overriding the EXEC 


The programmer may override any of the EXEC or DD statement 
specifications in a cataloged procedure. These new 
specifications remain in effect only for the duration of the job 
step. For a detailed description of overriding cataloged 
procedures, see the publication JCL 


Statement 


The EXEC statement in a cataloged procedure is overridden by 
specifying the changes and additions on the EXEC statement that 
invokes the cataloged procedure. The stepname should be 
specified when overriding the EXEC statement parameters. 


For example, the REGION parameter can be increased as follows: 
//LESTEP EXEC LKED, REGION. LKED=136K 


The rest of the specifications on the EXEC statement of 
procedure LKED remain in effect. 


If the PARM field is to be overridden, all the options specified 
in the cataloged procedure are negated. That is, if XREF, LIST, 
or NCAL is desired when overriding the PARM field, it must be 
respecified. In the following example, the OVLY option is added 
and the NCAL option is negated: 


//LESTEP EXEC  LKED,PARM.LKED="OVLY,XREF,LIST' 


As a result, the XREF and LIST options are retained, but the 
NCAL option is negated; when NCAL is negated, a SYSLIB DD 
statement must be added. 


If you use the LKEDG procedure and want to execute the load 
module just built, an efficient way is to specify the parameter 
LET in the LKED step and invoke the LKEDG procedure with the 
following EXEC statement: 


77 ssenpome EXEC LKEDG,PARM.LKED="XREF,LIST,NCAL,LET', 
7 


COND.GO=(8,LT,LKED) 
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Overriding DD Statements 


Each DD statement that is used to override a DD statement in the 
LKED step of either the LKED Procesute or the LKEDG procedure 
must begin with //LKED.ddname.. 





Any of the DD statements in the cataloged procedures can be 
overridden as long as the overriding DD statements are in the 
same order as they appear in the procedure. If any DD 
statements are not overridden, or overriding DD statements are 
included but are not in sequence, the specifications in the 
cataloged procedure are used. 


Only those parameters specified on the overriding DD statement 
are affected; the rest of the parameters remain as specified in 
the procedure. In the following example, the output load module 
is to be placed in a permanent library: 


//LIBUPDTE EXEC  LKED 


//LKED.SYSLMOD DD DSNAME=LOADLIBCPAYROLL),DISP=OLD 
//LKED.SYSIN DD DSNAME=OBJMOD, DISP=COLD, DELETE) 





Unit and volume information should be given if these data sets 
are not cataloged. 


As a result of the statements in the example, the LKED procedure 
1s used to process the object module in the OBJMOD data set. 

The output load module is stored in the data set LOADLIB with 
the name PAYROLL. The SPACE parameter on the SYSLMOD DD 
highs and the other specifications in the procedure remain 
in effect. 





( ADDING DD STATEMENTS 


DD statements for additional data sets can be supplied when 
using cataloged procedures. These additional DD statements must 
follow any overriding DD statements. 


Each additional DD statement for the LKED step must begin with 
//LKED.ddname... and, for the GO step, must begin with 
//GCO.ddname... . 


In the following example, the automatic library-call mechanism 
is to be used along with the LKEDG procedure: 


//CPSTEP EXEC LKEDG,PARM.LKED="XREF,LIST! 
//LKED.SYSLMOD DD DSNAME=LOADLIBCTESTER),DISP=OLD,... 
//LKED.SYSLIB DD DSNAME=SYL1.PLILIB, DISP=SHR 
//LKED.SYSIN DD x 


CObject module decks and/or control statements). 


1% 
//GO.SYSIN DD % 


(Data for execution step) 


7K 





The NCAL option is negated, and a SYSLIB DD statement is added 
sa peiah ‘is overriding SYSLMOD DD statement and the SYSIN DD 
statement. 
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This chapter summarizes the linkage editor control statements. 
The description of each statement includes: 


e What the statement does 

° The format of the statement 

° Placement of the statement in the input 
e Notes on use, if any 


e One or more examples that include job control language 
statements, when necessary 


The control statements are described in alphabetic order. 

Before using this chapter, the user should be familiar with the 
Ma a pete information on general format, format conventions, and 
placement. | 


General Format 


Each linkage editor control statement specifies an operation and 
one or more operands. Nothing must be written preceding the 
operation, which must begin in or after column 2. The operation 
must be separated from the operand by one or more blanks. 


A control statement can be continued on as many cards as 

necessary by terminating the operand at a comma, and by placing 

a nonblank character in column 72 of the card. Continuation 

must begin in column 16 of the next card. A symbol cannot be 

rae or is, it cannot begin on one card and be continued on 
e next. | 


Comments can be written ina utility statement, but they must be 
seh ao AM the last parameter of the operand field by one or 
more anks. 


Format Conventions 


The following conventions are used in the formats to describe 
the coding of the linkage editor control statements: 


e Boldface type indicates the exact characters to be entered. 
Such items must be entered exactly as illustrated Cin 
uppercase, if applicable). 


e Lowercase underscored type specifies fields to be supplied 
by the user. 


e Other punctuation Cparentheses, commas, spaces, etc.) must 
be entered as shown. 


e Braces { } indicate a choice of entry; unless a default is 
indicated, you must choose one of the entries. 


e Brackets {£ ] indicate an optional field or parameter. 


8 An ellipsis (...) indicates that multiple entries of the 
type immediately preceding the ellipsis are allowed. 


e Items separated by a vertical bar ( | ) represent 
y eet ae ag items. No more than one of the items may be 
selected. 
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Placement Information 


Linkage editor control statements are placed before, between, or 
after modules. They can be grouped, but they cannot be placed 
within a module. However, specific placement restrictions may 
be imposed by the nature of the functions being requested by the 
control statement. Any placement restrictions are noted. 
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ALIAS Statement 


The ALIAS statement specifies additional names for the output 
library member, and can also specify names of alternative entry 
points. Up to 16 names can be specified on one ALIAS statement, 
or separate ALIAS statements for one library member. The names 
are entered in the directory of the partitioned data set in 
addition to the member name. ~ 


FORMAT: The format of the ALIAS statement is: 
ALIAS {symbol lexternal name} | 


specifies an alternate name for the load module. When the 
module is executed, the main entry point is used as the 
starting point for execution. 


specifies a name that is defined as a control section name 
or entry name in the output module. When the module is 
called for execution, execution begins at the external name 
referred to. 


PLACEMENT: An ALIAS statement can be placed before, between, or 
after object modules or other control statements. It must 
precede eens statement used to specify the member name, if one 
is presen 


Notes: 


1. In an overlay program, an external name specified by the 
ALIAS statement must be in the root segment. 


2. No more than 16 alias names can be assigned to one output 
module. 


3. Each alias specified for a load module is retained in the 
directory entry for the module; the linkage editor does not 
delete an old alias. Therefore, each alias that is specified 
must be unique; assigning the same alias to more than one 
load module can cause incorrect module references. 


G. Obsolete alias names should be deleted from the PDS 
directory using a system utility such as IEHPROGM, to avoid 
future name conflicts. 


5. If the replace option is in effect for the output load 
module (that is, the load module built in this link-edit 
does or may replace an identically named load module in the 
output module library), the replace option is in effect for 
each ALIAS name for the load module as well as for the 
primary name. 


EXAMPLE: An output module, ROUTI1, is to be assigned two 
alternate entry points, CODE] and CODE2. In addition, calling 
modules have been written using both ROUT] and ROUTONE to refer 
to the output module. Rather than correct the calling modules, 
an alternative library member name is also assigned. 


ALIAS CODE], CODEZ2, ROUTONE 
NAME ROUT1 


Because CODE] and CODE2 are entry names in the output module, 
execution begins at the point referred to when these names are 
used to call the module. The modules that call the output 
module with the name ROUTONE now correctly refer to ROUT] at its 
main entry point. The names CODE], CODE2, and ROUTONE appear in 
the library directory along with ROUTI. 
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CHANGE Statement 





The CHANGE statement causes an external symbol to be replaced by 
the symbol in parentheses following the external symbol. The 
external symbol to be changed can be a control section name, an 
entry name, or an external reference. More than one such 
substitution may be specified in one CHANGE statement. 


FORMAT: The format of the CHANGE statement is: 


Lust externalsymbol (newsymbol } 
[,>externalsymbol (newsymbol )]... 


is the control section name, entry name, or external 
reference that is to be changed. 


is the name to which the external symbol is to be changed. 


PLACEMENT: The CHANGE control statement must be placed 
immediately before either the module containing the external 
symbol to be changed, or the INCLUDE control statement 
specifying the module. The scope of the CHANGE statement is 
across the immediately following module Cobject module or load 
module); the END record in the immediately following object 
module or the end-of-module indication in the immediately 

Lardet ipdabeel load module delimits the scope of the CHANGE 
statement. 


Notes: 


1. External references from other modules to a changed control 
section name or entry name remain unresolved unless further 
action is taken. 


2. If the external symbol specified on the CHANGE statement is 
misspelled, the symbol will not be changed. Linkage editor 
output, such as the cross-reference listing or module map, 
can be used to verify each change. 


3. When a REPLACE statement that deletes a control section is 
followed by a CHANGE statement with the same control section 
name, unpredictable results will occur. 


EXAMPLE 1: Two control sections in different modules have the 
name TAXROUT. Because both modules are to be link-edited 
together, one of the control section names must be changed. The 
module to be changed is defined with a DD statement named 
OBJMOQD. The control section name could be changed as follows: 


//OBJMOD DD DSNAME=TAXES, DISP=COLD,KEEP),... 
4/7 SYSLIN DD 3 

CHANGE TAXROUTCSTATETAX) 

INCLUDE OBJMOD 


7% 





As a result, the name of control section TAXROUT in module TAXES 
is changed to STATETAX. 


Chapter 5. Specifying an Operation with Control Statements 69 











EXAMPLE 2: A load module contains references to TAXROUT that 
must now be changed to STATETAX. This module is defined with a 
DD statement named LOADMOD. The external references could be 

S auged at the same time the control section name is changed, as 
ollows: 


//OBJMOD DD DSNAME=TAXES, DISP=COLD, DELETE)D,... 
//\QADMOD DD ale LOADLIB, DISP=OLD,... 
S/SYSLIN DD 

CHANGE TAXROUT(STATETAX) 

INCLUDE OBJMOD 


CHANGE TAXROUTCSTATETAX) 
INCLUDE LOADMODCINVENTRY) 


7% 





As a result, control section name TAXROUT in module TAXES and 
o. etne ee lorerence TAXROUT in module INVENTRY are both changed 
o : 
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ENTRY Statement 


The ENTRY statement specifies the symbolic name of the first 
instruction to be executed when the program is called by its 
module name for execution. An ENTRY statement should be used 
whenever a module is reprocessed by the linkage editor. If more 
than one ENTRY statement is encountered, the first statement 
peeee ee the main entry point; all other ENTRY statements are 
ignored. 


FORMAT: The format of the ENTRY statement is: 


is defined as either a control section name or an entry 
name ina linkage editor input module. 


PLACEMENT: An ENTRY statement can be placed before, between, or 
after object modules or other control statements. It must 
precede the NAME statement for the module, if one is present. 


Notes: 


1. In an overlay program, the first instruction to be executed 
must be in the root segment. 


2. The external name specified must be the name of an 
instruction, not a data name, if the module is to be 
executed. 


na In the following example, the main entry point is 


//LOADLIB DD DSNAME=LOADLIB,DISP=OLD,... 
f/SYSLIN DD X 

ENTRY INIT1 

INCLUDE LOADLIBCREAD, WRITE) 


ENTRY READIN 
7% 





INIT1 must be either a control section name or an entry name in 
the linkage editor input. The entry point specification of 
READIN is ignored. 
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EXPAND Statement 


The EXPAND statement lengthens control sections or named common 
sections by a specified number of bytes. 


FORMAT: The format of an EXPAND statement is 


EXPAND name (xx.2x«x ) 
C»>name(xxxx J]... 


name . 
is the symbolic name of a common section or control section 
whose length is to be increased. 


is the decimal number of bytes to be added to the length of 
a common section. The maximum is 4095 for each section 
indicated. Binary zeros will be added for an expanded 
control section. 


The EXPAND statement is followed by a message, IEW0740, that 
indicates the number of bytes added to the control section and 
the offset, relative to the start of the control section, at 
which the expansion begins. The effective length of the 
expansion is given in hexadecimal and may be greater than the 
specified length if, after the specified expansion, padding 
bytes must be added for alignment of the next control section or 
named common section. 


PLACEMENT: An EXPAND statement can be placed before, between, 
or after other control statements or object modules. However, 
the statement must follow the module containing the control or 
named common section to which it refers. If the control section 
or named common section is entered as the result of an INCLUDE 
statement, the EXPAND statement must immediately follow the 
INCLUDE statement. 


Note: EXPAND should be used with caution so as not to increase 

the length of a program beyond its own design limitations. For 

example, if space is added to a control section beyond the range 
of its base register addressability, that space is unusable. 


EXAMPLE: In the following example, EXPAND statements add a 
250-byte patch area (initialized to zeros) at the end of control 
section CSECT1 and increase the length of named common section 
COM1 by 400 bytes. 


//LKED PGM=HEWL 

S/SYSPRINT D SYSOUT=A 

//SYSUT1 UNIT=SYSDA, SPACE=CTRK, €10,4)) 
4/7SYSLMOD DSNAME=PDSX, DISP=OLD 

S/SYSLIN DSNAME=&&LOADSET, DISP=COLD,PASS), 


Sf UNIT=SYSDA 

// x 
EXPAND CSECT10250) 
EXPAND COM1¢4003) 
NAME | MODICR)D 

4 ® 
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IDENTIFY Statement 


The IDENTIFY statement specifies any data supplied by the user 
to be entered into the CSECT identification CIDR) records for a 
particular control section. The statement can be used either to 
supply descriptive data for a control section or to provide a 
means of associating system-supplied data with executable code. 


FORMAT: The format of the IDENTIFY statement is: 


IDENTIFY csectname('data')JL,csectname("data'}]... 


is the symbolic name of the control section to be 
identified. 


specifies up to 40 EBCDIC characters of identifying 
information. The user may supply any information desired 
for identification purposes. 


The rules of syntax for the operand field are: | 


1. No blanks or characters may appear between the left 
parenthesis and the leading single quotation mark nor 
between the trailing single quotation mark and the right 
parenthesis. 


2. The data field consists of from 1 to 40 characters; 
therefore, a null entry must be represented, minimally, by a 
Single blank. 


3. Blanks may appear between the leading single quotation mark 
and the trailing single quotation mark. Each blank counts 
as 1 character toward the 40-character limit. 


G4. A single quotation mark between the leading quotation mark 
and the trailing quotation mark is represented by 2 
consecutive quotation marks. The pair. of quotation marks 
counts as 1 character toward the 4G0-character Limit. 


5. Any EBCDIC character may appear between the leading 
quotation mark and the trailing quotation mark. Each 
oe counts as 1 character toward the 40-character 

imit. 


6. The IDENTIFY statement may be continued; however, a whole 
operand must appear on a single card image and at least 1 
whole operand must appear on each card image of the 
continued statement. 


7. If a leading quotation mark is found, all characters are 
absorbed until a trailing quotation mark is found or the 
GO-character limit is exhausted. 


8. Blanks may not appear between the CSECT name and the left 
parenthesis. 


9. A blank following a left parenthesis terminates the operand 
field; a blank following a comma that terminates an operand 
also terminates the operand field of that card image. 


PLACEMENT: An IDENTIFY statement can be placed before, between, 
or after other control statements or object modules. The 
IDENTIFY statement must follow the module containing the control 
pred to be identified or the INCLUDE statement specifying the 
module. 


Note: When two or more IDENTIFY statements specify the same 
CSECT name, only the last statement is effective. 
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EXAMPLE: In the following example, IDENTIFY statements are used 


to identify the source level of a control section, a PTF on 
application to a control section, and the functions of several fo 
control] sections. — ee 


//\KED PGM=HEWL 

S/SYSPRINT D SYSOUT=A 

//SYSUTI UNIT=SYSDA, SPACE=C(TRK, (10,5)) 
//SYSLMOD DSNAME=LOADSET, DISP=OLD 
7/QLDMOD DSNAME=OLD.LOADSET, DISP=O0OLD 
//PTFMOD DSNAME=PTF .OBJECT, DISP=OLD 
//SYSLIN x 


Cinput object deck for a control section named FORT) 


IDENTIFY FORTC'LEVEL 03°) 

INCLUDE PTFMODCCSECT4) 

IDENTIFY CSECT4C'PTF99999°) 

INCLUDE OL DMODCPROG1) 

IDENTIFY CSECT1IC'I/ZO ROUTINE'), 
CSECT2C"SORT ROUTINE'), 
CSECT3C*SCAN ROUTINE’) 





Execution of this example produces IDR records containing the 
following identification data: 


e The name of the linkage editor that produced the load 
module, the linkage editor version and modification level, 
and the date of the current linkage editor processing of the 
module. This information is provided automatically. 


e User-supplied data describing the functions of several ws 
control sections in the module, as indicated on the third 
IDENTIFY statement. 


e If the language translator used supports IDR, the 
identification records produced by the linkage editor also 
contain the name of the translator that produced the object 
module, its version and modification level, and the data of 
compilation. 


The IDR records created by the linkage editor can be referenced 


by using the LISTIDR function of the service aid program 
AMBLIST. For instructions on how to use AMBLIST> see 
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INCLUDE Statement 





The INCLUDE statement specifies sequential data sets and/or 
libraries that are to be sources of additional input for the 
linkage editor. INCLUDE statements are processed in the order 
in which they appear in the input. However, the sequence of 
data sets and modules within the output load module does not 
necessarily follow the order of the INCLUDE statements. If the 
order of the CSECTs within the module is significant, the user 
must specify the desired sequence by using order cards. 


FORMAT: The format of the INCLUDE statement is: 


INCLUDE ddnamel(membernamel,...1)1 


[,ddnamel (membernamel,...1)]]... 





is the name of a DD statement that describes either a 
sequential or a partitioned data set to be used as 
additional input to the linkage editor. For a sequential 
data set, ddname is all that must be specified. For a 
partitioned data set, at least one member name must also be 
specified. 


is the name of or an alias for a member of the library 
defined in the specified DD statement. The membername must 
not be specified again on the DD statement. 


PLACEMENT: An INCLUDE statement can usually be placed before, 
between, or after object modules or other control statements. 
When link-editing the nucleus, however, any ORDER statements 
used should precede the INCLUDE statements. 


Note: A NAME statement in any data set specified in an INCLUDE 
statement is invalid; the NAME statement is ignored. All other 
control statements are processed. 


EXAMPLE 1: In the following sveuele: an INCLUDE statement 
specifies two data sets to be the input to the linkage editor: 


4/0BJMOD DD DSNAME=&& OBJECT, DISP=COLD, DELETE) 
//LOADMOD DD DSNAME=LOADLIB,DISP=SHR,... 


//SYSLIN 


DD 
INCLUDE OBJMOD, LOADMOD(TESTMOD, READMOD) 
7% 





Note that a DD statement must be supplied for every ddname 
specified in an INCLUDE statement. 


EXAMPLE 2: Two separate INCLUDE statements could have been used 
in the preceding example, as follows: 


INCLUDE OBJMOD 
INCLUDE LOADMOD(TESTMOD, READMOD) 
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INSERT Statement 


The INSERT statement repositions a control section from its 
position in the input sequence to a segment in an overlay 
structure. However, the sequence of control sections within a 


segment is not necessarily the order of the INSERT statements. 


If a symbol specified in the operand field of an INSERT 
statement is not present in the external symbol dictionary, it 
is entered as an external reference. If the reference has not 
been resolved at the end of primary input processing, the 
automatic library-call mechanism attempts to resolve it. 


FORMAT: The format of the INSERT statement is: 


is the name of the control section to be repositioned. A 
particular control section can appear only once within a 
load module. 


PLACEMENT: The INSERT statement must be placed in the input 
sequence following the OVERLAY statement that specifies the 
origin of the segment in which the control section is to be 
positioned. If the control section is to be positioned in the 
root segment, the INSERT statement must be placed before the 
first OVERLAY statement. 


Note: Control sections that are positioned in a segment must 
eee all address constants to be used during execution 
unless: 


e Ve oes address constants are located in a segment in the 
path. 


e The V-type address constants used to pass control to another 
segment are located in the path. If an exclusive reference 
is beet the V-type address constant must be in a common 
segment. 


® The V-type address constants used with the SEGLD and SEGHT 
macro instructions are located in the segment. 


EXAMPLE: The following INSERT Cand OVERLAY) statements specify 
the overlay structure shown in Figure 23 on page 77: 


EXEC PGM=HEWL,PARM="OVLY,XREF,LIST'® 


7/7SYSLIN DD 
INSERT CSA 
INSERT CSB 
OVERLAY ALPHA 
INSERT CSC,CSD 
OVERLAY ALPHA 
INSERT CSE 

7% 
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LIBRARY Statement 





CSC 


CSD 
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Figure 23. Overlay Structure for INSERT Statement Example 


The 


LIBRARY statement can be used to specify: 


Additional automatic call libraries, which contain modules 
used to resolve external references found in the program. 


Restricted no-call function: External references that are 
not to be resolved by the automatic library call mechanism 
during the current linkage editor job step. 


Never-call function: External references that are not to be 
resolved by the automatic library call mechanism during any 
linkage editor job step. 


Combinations of these functions can be written in the same 
LIBRARY statement. 


FORMAT: The format of the LIBRARY statement is: 


LIBRARY {ddnamel(membernamel,...]) 





dna 


( 
Cexternalreferencel,...1) 
¥ (exter nalr efer encel,...1l)}»... 


is the name of a DD statement that defines a library. 


is the name of or an alias for a member of the specified 
library. Only those members specified are used to resolve 
references. 
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is an external reference that may be unresolved after 
primary input processing. The external reference is not to 
be resolved by automatic library call. 


indicates that the external reference is never to be 
resolved; if the * Casterisk) is missing, the reference is 
left unresolved only during the current linkage editor run. 


PLACEMENT: A LIBRARY statement can be placed before, between, 
or after object modules or other control statements. 


Notes: 


1. If the unresolved external symbol is not a member name in 
the library specified, the external reference remains 
unresolved unless defined in another input module. 


2. If the NCAL option is specified, the LIBRARY statement 
cannot be used to specify additional call libraries. 


3. Members called by automatic library call are placed in the 
root segment of an overlay program, unless they are 
repositioned with an INSERT statement. 


G4. Specifying an external reference for restricted no-call or 
never-call by means of the LIBRARY statement prevents the 
external reference from being resolved by automatic 
inclusion of the necessary module from an automatic call 
library; it does not prevent the external reference from 
being resolved if the module necessary to resolve the 
reference is specifically included or is included as part of 
an input module. 


EXAMPLE: The following example shows all three uses of the 
LIBRARY statement: 


f/f EXEC PGM=HEWL,PARM="LET,XREF,LIST' 
//TESTLIB DD DSNAME=TEST, DISP=SHR,... 


//SYSLIN DD 


x 
LIBRARY TESTLIBCDATE, TIME), CFICACOMP) , XCSTATETAX) 
7% 





As a result, members DATE and TIME from the additional library 
TESTLIB are used to resolve external references. FICACOMP and 
STATETAX are not resolved; however, because the references 
remain unresolved, the LET option must be specified on the EXEC 
statement if the module is to be marked executable. In 
addition, STATETAX will not be resolved in any subsequent 
reprocessing by the linkage editor. 
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MODE Statement 


The MODE statement specifies the residence mode for the output 
load module and/or the addressing mode for all the entry points 
into the load module (the main entry point, its true aliases, 
and all the alternate entry points). 


FORMAT: The format of the MODE statement is as follows: 
MODE modespec(»modespec ) 


is either of the following: 


e The designation of an addressing mode for the output load 
module by one of the following: 


—-  AMODEC24) 
~-  AMODEC31) 
~-  AMODECANY) 


e The designation of residence mode for the output load module 
by one of the following: 


—-  RMODEC24) 
—-  RMODECANY) 


PLACEMENT: The MODE control statement can be placed before, 
between, or after object modules or other control statements. 
It debe precede the NAME statement for the module, if one is 
present. 


Notes: 


1. The residence mode assigned by the MODE control statement 
overrides the residence mode accumulated from the input 
control sections and private code. The residence mode 
assigned by the MODE control statement also overrides the 
residence mode assigned by the RMODE parameter in the PARM 
field of the EXEC statement. 


2. The addressing mode assigned by the MODE control statement 
overrides the separate addressing modes found in the ESD 
data for the control sections within which the entry points 
are located. The addressing mode assigned by the MODE 
control statement overrides the addressing mode assigned by 
the AMODE parameter in the PARM field of the EXEC statement. 


3. If more than one MODE control statement is encountered in 
the link-edit of a load module, the last valid mode 
specification is used. Likewise, if a mode specification 
occurs more than once within a MODE statement, the last 
valid mode specification is used. 
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4. If only one value, either AMODE or RMODE, is specified in 
the MODE control statement, the other value is implied 
according to the following table: — 


Value Specified 
AMODE=ANY 
RMODE=ANY | AMODE=31 


If only an RMODE of 24 is specified, no overriding AMODE 
value is assigned; instead, the AMODE value in the ESD data 
for the main entry point, a true alias, or an alternate 
ed point is used in generating its respective directory 
entry. 
















5. In generating a directory entry for either the main entry 
point, a true alias, or an alternate entry point, the 
linkage editor validates the combination of the AMODE value 
and the RMODE value, as specified by the user in the MODE 
control statement(s), according to the table below: 


a 


6. If the AMODE/RMODE combination resulting from the MODE 
control statement(s) is invalid, an error message is issued 
and the linkage editor ignores the MODE control statement(s) 
as the source of AMODE/RMODE data. 







EXAMPLE: In the following example, an output load module, named 
NEWMOD, is created; it is given a true alias of TESTMOD; the 
residence mode for the load module is ANY; the addressing mode 
for both the main entry point, NEWMOD, and the true alias, 
TESTMOD, is 3l. 


7/SVYSLMOD DD DSN=TESTLOAD, DISP=MOD,... 
//SYSLIN DD XxX 


MODE AMODE(31),RMODECANY) 
ALIAS TESTMOD 
NAME NEWMOD 
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NAME Statement 


The NAME statement specifies the name of the load module created 
from the preceding input modules, and serves as a delimiter for 
input to the load module. As a delimiter, the NAME statement 

allows multiple load module processing in one linkage editor job 

step. The NAME statement can also indicate that the load module 
Hidde an identically named module in the output module 
ibrary. 


FORMAT: The format of the NAME statement is: 


is the name to be assigned to the load module that is 
created from the preceding input modules. 





(R) 
: indicates that this load module replaces an identically 
named module in the output module library. If the module 
is not a replacement, the parenthesized value (R) should 

not be specified. 


PLACEMENT: The NAME statement is placed after the last input 
ler or control statement that is to be used for the output 
module. 


Notes: 
1. Any ALIAS statement used must precede the NAME statement. 


2. A NAME statement found in a data set other than the primary 
( input data set is invalid. The statement is ignored. 


EXAMPLE: In the following example, two load modules, RDMOD and 
WRTMOD, are produced by the linkage editor in one job step: 


4/SYSLMOD DD DSNAME=AUXMODS, DISP=MOD,... 
//NEWMOD DD DSNAME=&&WRTMOD, DISP=OLD 
//SYSLIN BD DSNAME=&&RDMOD, DISP=OLD 

47 x 


NAME RDMODCR) 

INCLUDE NEWMOD 

NAME WRTMOD 
7% 





As a result, the first module is named RDMOD and replaces an 
identically named module in the output module library AUXMODS; 
the second module is named WRIMOD and is added to the library. 
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ORDER Statement 


The ORDER statement indicates the sequence in which control ae 
sections or named common areas appear in the output load module. wy 
The control sections or named common areas appear in the 

sequence in which they are specified on the ORDER statement. 

When multiple ORDER statements are used, their sequence further 
determines the sequence of the control sections or named common 

areas in the output load module; those named on the first 

statement appear first, and so forth. 


FORMAT: The format of the ORDER statement is: 


ORDER {common area namel(PJ][csectnamel(PJ1},... 


is the name of the common area to be sequenced. 


is the name of the control section to be sequenced. 


(P) 
indicates that the starting address of the control section 
or named common area is to be on a page boundary within the 
load module. The control sections or common areas are 
aligned on 4K-byte page boundaries. 


PLACEMENT: An ORDER statement can usually be placed before, 
between, or after object modules or other control statements. 
When link-editing the nucleus; however, any ORDER statements 
used should precede the INCLUDE statements. 


Notes: 


1. A control section or common area can be named on only one | 
ORDER statement. If the same name is used more than once, Se 
except when it is the last operand on one ORDER statement 
and the first operand on the next, the name is ignored, as 
is the balance of the control statement on which it appears. 


2. The control sections and common areas named as operands can 
appear in either the primary input or the automatic call 
library, or both. 


3. If a control section or a named common area is changed by a 
CHANGE or REPLACE control statement and sequencing is 
desired, specify the new name on the ORDER statement. The 
ORDER statement refers to the control section by its new 
name. 


EXAMPLE: In this example, the control sections in the load 
module LDMOD are arranged by the linkage editor according to the 
sequence specified on ORDER statements. The page boundary 
alignments and the control section sequence made as a result of 
these statements are shown in Figure 24 on page 83. Assume each 
control section is 1K byte in length. 





82 MVS/XA Linkage Editor and Loader User's Guide 








JCL and Control Statements 


//SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,... 


//SYSLIN DD * 


ORDER ROOTSEG(P) ,MAINSEG, SEG1 ,SEG2 
ORDER SEG3 (P) ,ENTRY1 

ORDER FSTPART ,SESECTA ,SESECTB (P) 
INCLUDE SYSLMOD(LDMOD) 


/* 


Figure 24. Output Load Module for ORDER Statement Example. 





Output Load Module 


LDMOD 


ROOTSEG 


MAINSEG 






SEG1 


SEG2 





4K 
SEG3 









ENTRY I 


FSTPART 


SESECTA 


8K 
SESECTB 


The control section 


name PART1 is changed by a CHANGE statement to FSTPART. The ORDER 
statement refers to the control section by its new name. 
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OVERLAY Statement 


The OVERLAY statement indicates either the beginning of an 
overlay segment, or of an overlay region. Because a segment or 
a region is not named, the programmer identifies it by giving 
its origin Cor load point) a symbolic name. This name is then 
used on an OVERLAY statement to signify the start of a new 
segment or region. 


FORMAT: The format of the OVERLAY statement is: 


OVERLAY symbol (REGION) ! 


is the symbolic name assigned to the origin of a segment. 
This symbol is not related to external symbols in a module. 


(REGION) 
specifies the origin of a new region. 


PLACEMENT: The OVERLAY statement must precede the first module 

of the next segment, the INCLUDE statement specifying the first 
module of the segment, or the INSERT statement specifying the 
control sections to be positioned in the segment. 


Notes: 


1. The OVLY option must be specified on the EXEC statement when 
OVERLAY statements are to be used. 


2. The sequence of OVERLAY statements should reflect the order 
of the segments in the overlay structure from top to bottom, 
left to right, and region by region. 

3. No OVERLAY statement should precede the root segment. 


EXAMPLE: The following OVERLAY and INSERT statements specify 
the overlay structure in Figure 25 on page 85. 


47 EXEC PGM=HEWL,PARM="OVLY,XREF,LIST' 


//SYSLIN DD DSNAME=&&0BJ,... 
oS, DD x 


INSERT CSA 
OVERLAY ONE 
INSERT CSB 
OVERLAY TWO 
INSERT CSC 
OVERLAY TWO 
INSERT CSD 
OVERLAY ee 
INSERT CSE,CSF 
OVERLAY THREECREGION) 
INSERT CSH 
OVERLAY THREE 
INSERT CSI 

x 
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Figure 25. Overlay Structure for OVERLAY Statement Example 
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PAGE Statement 


The PAGE statement aligns a control section or named common area (t | 
on a 4K-byte page boundary in the load module. Qe Y 


FORMAT: The format of the PAGE statement is: 
| PAGE {common area namelcsectname}>... 


is the name of the common area to be aligned on a page 
boundary. 


is the name of the control section to be aligned on a page 
boundary. 


PLACEMENT: The PAGE statement can be placed before, between, or 
after object modules or other control statements. 


Notes: 


1. If a control section or a named common area is changed by a 
CHANGE or REPLACE control statement, and page alignment is 
wanted, specify the new name in the PAGE statement. 


2. The control sections and common areas named as operands can 
appear in either the primary input or the automatic call 
library, or both. 


EXAMPLE: In this example, the control sections in the load 
module LDMOD are aligned on page boundaries as specified in the 
following PAGE statement: 


PAGE ALIGN, BNDRYGK, EIGHTK 
The job control statements and linkage editor control statements 


as well as the output load module are shown in Figure 26 on 
page 87. Assume each control section is 3K bytes in length. 
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JCL And Control Statements 


/ /UKED EXEC PGM=HEWL,PARM=,... 
J /SYSLMOD DD DSNAME=PVTLIB,DISP=OLD,... 
//SYSLIN DD * 
PAGE ALIGN ,BNDRY4K,EIGHTK 
INCLUDE SYSLMOD (LDMOD) 
/* 
Figure 26. 


Chapter 5. 


Output Load Module 


LDMOD 


Empty Space 
Due to Boundary 
Alignment 


BNDRY4K 


Empty Space 
Due to Boundary 
Alignment 


EIGHTK 





Output Load Module for PAGE Statement Example 
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REPLACE Statement 


The REPLACE statement specifies one or more of the following: 


e The replacement of one control section with another 


e The deletion of a control section 
e The deletion of an entry name 


When a control section is replaced, all references within the 
input module to the old control section are changed to the new 
control section. Any external references to the old control 
section from other modules are unresolved unless changed. 


When a control section is deleted, the control section name is 
also deleted from the external symbol dictionary, unless 
references are made to the control section from within the input 
module. If there are any such references, the control section 
name is changed to an external reference. External references 
from other modules to a deleted control section also remain 
unresolved. 


When deleting an entry name, if there are any references to it 
within the same input module, the entry name is changed to an 
external reference. 


FORMAT: The format of the REPLACE statement is: 
REPLACE {csectname-l1f (csectname-2)],entryname} 


is the name of a control section. If only csectname-] ay 
used, the control section is deleted; if csectname-2 i 

meet eae the first control section is replaced sath: the 
second. 


is the entry name to be deleted. 


PLACEMENT: The REPLACE statement must immediately precede 
either (1) the module containing the control section or entry 
name to be replaced or deleted, or (2) the INCLUDE statement 
specifying the module. The scope of the REPLACE statement is 
across the immediately following module Cobject module or load 
module). The END record in the immediately following object 
module or the end-of-module indication in the load module 
terminates the action of the REPLACE statement. If the REPLACE 
statement is the last control statement in the SYSLIN data set, 
and there are unresolved external references to be resolved from 
SYSLIB, the REPLACE function operates on the first module from 
SYSLIB by an AUTO CALL. 


Notes: 


1. Unresolved external references are not deleted from the 
output module even though a deleted control section contains 
the only reference to a symbol. 


2. When some but not all control sections of a separately 
assembled module are to be replaced, A-type address 
constants that refer to a deleted symbol will be incorrectly 
resolved, unless the entry name is at the same displacement 
Mi Peds origin in both the old and the new control 
sections. 


3. If no INCLUDE statement follows the REPLACE statement, one 
| ecoue may be left out of AUTO CALL. Message LEWO1L32 is 
issued. 


G. If the control section identified as csectname-l] (specified 
on the REPLACE statement) is misspelled, the control section 
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will not be replaced or deleted. Linkage editor output, 
such as the cross-reference listing and module map, can be 
used to verify each change. 


EXAMPLE: In the following example, assume that control section 
INT7 is in member LOANCOMP and that control section INT&8&, which 
is to replace INT7, is in data set &&NEWINT. Also assume that 
control section PRIME in member LOANCOMP is to be deleted. 


//NEWMOD DD DSNAME=&&NEWINT, DISP=COLD, DELETE) 
//7QLDMOD DD DSNAME=PVTLIB,DISP=OLD,... 
Z/SYSLIN DD % 

ENTRY MAINENT 


INCLUDE NEWMOD 
REPLACE INT7CINT8),PRIME 
J INCLUDE OLDMODCLOANCOMP ) 
x 





As a result, INT7 is removed from the input module described by 
the OLDMOD DD statement, and INT& replaces INT7. All references 
to INT7 in the input module now refer to INT&. Any references 
to INT? from other modules remain unresolved. If there are no 
references to PRIME in LOANCOMP, control section PRIME is 
deleted; the control section name is also deleted from the 
external symbol dictionary. 
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SETCODE Statement 


The SETCODE statement assigns the specified authorization code 


to the output load module. The authorization code is placed in 


the directory entry for the output load module. 
FORMAT: The format of the SETCODE statement is as follows: 


SETCODE | AClauthorizationcode) 


is 1 to 3 decimal digits specifying a value from 0 to 255. 


PLACEMENT: A SETCODE statement can be placed before, between, 
or after object modules or other control statements. It must 
precede the NAME statement for the module, if one is present. 


Notes: 


1. The authorization code assigned by the SETCODE statement 
overrides the authorization code assigned by the AC 
parameter in the PARM field of the EXEC statement. 


2. If more than one SETCODE statement is encountered in the 
link-edit of a load module, the last valid authorization 
code assigned is used. 


3. The operand "ACC )* results in an authorization code of 
zero. 


EXAMPLE: In the following example, an authorization code of 1 
1S assigned to the output load module MODI. 


//LKED PGM=HEWL 

//SYSPRINT SYSOUT=A 

Z/SYSUTI UNIT=SYSDA, SPACE=CTRK, (10,5)) | 
//SYSLMOD DSNAME=SYS1.LINKLIB, DISP=OLD 
Z/SYSLIN DSNAME=&&LOADSET, DISP=COLD,PASS) 


17 UNIT=SYSDA 
4/ DD % 

SETCODE AC(1) 

NAME MODICR) 
7% 
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SETSSI Statement 


( The SETSSI statement specifies hexadecimal information to be 
7 placed in the system status index of the directory entry for the 
output module. 


FORMAT: The format of the SETSSI statement is: 


represents 8 hexadecimal characters (0 through 9 and A 
through F) to be placed in the 4-byte system status index 
of the output module library directory entry. 


PLACEMENT: The SETSSI statement can be placed before, between, 
or after object modules or other control statements. If one is 
present, it must precede the NAME statement for the module. 





Note: A SETSSI statement must be provided whenever an 
IBM-supplied load module is reprocessed by the linkage editor. 
If the ace vonens is omitted, no system status index information 
is present. 
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The linkage editor performs editing functions either 
automatically or as directed by control statements. These 
editing functions provide for program modification on a control 
section basis. That is, they make it possible to modify a 
control section within an object or load module, without 
recompiling the entire source program. 


The editing functions can modify either an entire control 
section or external symbols within a control section. Control 
sections can be deleted, replaced, or arranged in sequence} 
external symbols can be deleted or changed. (CExternal symbols 
are control section names, entry names, external references, 
named common areas, or pseudoregisters. ) 


Whatever function is used, it is requested in reference to an 
anput module. The resulting output load module reflects the 
request. That is, no actual change, deletion, or replacement is 
made to an input module. The requested alterations are used to 
control linkage editor processing (Figure 27). 


Input Modules JCL and Control Statements Output Load Module 
MODA1 
| 
Corcn. a 


% //SYSLMOD DD DSNAME=NEWLIB(MODA1A2), 
//MODATWO DD DSNAME=MODA2,... 
//SYSLIN DD DSNAME=MODA1, 

MODA2 // DD * 


ENTRY  CSECT3 
REPLACE CSECT2(CSECTA ) 
CSECT! an INCLUDE MODATWO 
CSECT2 i 
—T 


Figure 27. Editing a Module 


anc a @ 


CSECTA 









CSECT3 





Editing Conventions 
In requesting editing functions, certain conventions should be 
followed to ensure that the specified modification is processed 
correctly. These conventions concern the following items: 
e Entry points for the new module 
e Placement of control statements 


e Identical old and new symbols 


92 MVS/XA Linkage Editor and Loader User's Guide 


ee 


























ENTRY POINTS: Each time the linkage editor reprocesses a load 
module, the entry point for the output module should be 
specified in one of two ways: 


e Through an ENTRY control statement. 


e Through the assembler-produced END statement of an input 
object module, if one is present. If the entry point 
specified in the assembler-produced END statement is not 
defined in the object module, the entry name must be defined 
as an external reference. 


The entry point assigned must be defined as an external name 
within the resulting load module. 


PLACEMENT OF CONTROL STATEMENTS: The control statement (such as 
CHANGE or REPLACE) used to specify an editing function must 
precede either the module to be modified, or the INCLUDE 
statement that specifies the module. If an INCLUDE statement 
specifies several modules, the CHANGE or REPLACE statement 
applies only to the first module included. 


IDENTICAL OLD AND NEW SYMBOLS: The same symbol should not 
appear as both an old external symbol and a new external symbol 
in one linkage editor run. If a control section is to be 
replaced by another control section with the same name, the 
linkage editor handles this automatically (see "Automatic 
Replacement" on page 96) 
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CHANGING EXTERNAL SYMBOLS 


The linkage editor can be directed to change an external symbol 
to a new symbol while processing an input module. External 
references and address constants within the module automatically 
refer to the new symbol. External references from other modules 
to a changed external symbol must be changed with separate 
control statements. 


Both the old and the new symbols are specified on either a 
CHANGE control statement or a REPLACE control statement. The 
use of the old symbol within the module determines whether the 
new symbol becomes a control section name, an entry name, or an 
external reference. The old symbol appears first, followed by 
the new symbol in parentheses. 


The CHANGE control statement changes a control section name, an 
entry name, or an external reference. The REPLACE statement 
changes or deletes an entry name; if the symbols on a REPLACE 
statement are control section names, the entire control section 
is pees or deleted (see "Replacing Control Sections" on 
page : 


The CHANGE statement must immediately precede either the input 
module that contains the external symbol to be changed, or the 
INCLUDE statement that specifies the input module. The scope of 
the CHANGE statement is across the immediately following module 
Cobject module or load module). The END record in the 
immediately following object module or the end-of-module 
indication in the load module terminates the action of the 
CHANGE statement. 


In the following example, assume that SUBONE is defined as an 
external reference in the input load module. A CHANGE statement 
is mae a change the external reference to NEWMOD (Figure 28 on 
page ; 


7/SYSLMOD DD DSNAME=PVTLIB, DISP=OLD, UNIT=3350, 
/ VOLUME=SER=PVT002 
//SYSLIN DD x 

BEGIN 


SUBONECNEWMOD) 
SYSLMODCMATINROUT )D 
MAINROUTCR) 
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Input Module JCL and Control Statements Output Load Module 





MAINROUT MAINROUT 


MAINEP ENTRY 


BEGIN ENTRY 


CALE SUBONE //SYSLMOD DD DSNAME=PVTLIB,... CaN AO? 
//SYSLIN DD * ; 
; ENTRY MAINEP 
CALL SUBONE a. CHANGE SUBONE( NEWMOD ), BEGIN(MAINEP) | CALL NEWMOD 
, INCLUDE SYSLMOD( MAINROUT ) ; 
NAME MAINROUT(R) 
/* 


CALL NEWMOD 


CALL SUBONE 





Figure 28. Changing an External Reference and an Entry Point 


In the load module MAINROUT, every reference to SUBONE is 
changed to NEWMOD. Note also that the INCLUDE statement 
specifies a ddname of SYSLMOD. This allows a library to be used 
both as input and as the output module library. 


, : More than one change can be specified on the same control 
statement. If, in the same example, the entry point is also to 

~ be changed, the two changes can be specified at once (see 
Figure 28). 


//SYSLMOD DD DSNAME=PVTLIB, DISP=OLD,UNIT=3350, 
17 VOLUME=SER=PVT002 
“/SYSLIN DD * 

ENTRY MAINEP 


CHANGE SUBONECNEWMOD) , BEGINCMAINEP ) 
INCLUDE SYSLMODCMAINROUT ) 
NAME MAITNROUTCR) 

7% 





The main entry point is now MAINEP instead of BEGIN. The ENTRY 
control statement specifies the new entry point, because this is 
the source of the name that is entered in the library directory 
entry for the load module's entry point. 


REPLACING CONTROL SECTIONS 


An entire control section can be replaced with a new control 
section. Control sections can be replaced either automatically 
or with a REPLACE control statement. Automatic replacement acts 
upon all input modules; the REPLACE statement acts only upon the 
module that follows it. 
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Notes: 


1. Any CSECT identification CIDR) records associated with a 
particular control section are also replaced. 


2. (For Assembler language programmers only.) When some but 
not all control sections of a separately assembled module 
are to be replaced, A-type address constants that refer to a 
deleted symbol will be incorrectly resolved unless the entry 
name is at the same displacement from the origin in both the 
old and the new control section. If all control sections of 
a seroraxery assembled module are replaced, no restrictions 
apply. | 


AUTOMATIC REPLACEMENT 


Control sections are automatically replaced if both the old and 
the new control section have the same name. The first of the 
identically named control sections processed by the linkage 
editor is made a part of the output module. All subsequent 
identically named control sections are ignored; external 
references to identically named control sections are resolved 
with respect to the first one processed. Therefore, to cause 
automatic replacement, the new control section must have the 
same name as the control section to be replaced, and must be 
processed before the old cantrol section. 


Caution: Automatic replacement applies to duplicate control 
section names only; if duplicate entry points exist in control 
sections with different names, a REPLACE control statement must 
be used to specify the entry point name. If a control section 
being automatically replaced contains unresolved external 
references and the control section replacing it does not, the 
parameter NCAL must be specified or the unresolved external 
references must be explicitly deleted using the REPLACE 
statement or marked for restricted no-call or never-call using 
the LIBRARY statement; otherwise, the unresolved external 
reference is retained. 


NOTE ON OVERLAY PROGRAMS: When identically named control 
sections appear in modules being placed in an overlay structure, 
the second and any subsequent control sections with that name 
are ignored. This occurs whether the modules are in segments in 
the same path or in exclusive segments. Resolution of external 
references may therefore cause invalid exclusive references. 
Invalid exclusive references cause the linkage editor to mark 
the output module not executable unless the exclusive call 
CXCAL) option is specified on the EXEC statement (see "Chapter 
G4. Specifying JCL to Run a Linkage Editor Job" on page 36). 


Example 1 


An object module deck contains two control sections, READ and 
WRITE; member INOUT of library PVTLIB also contains a control 
section WRITE. 


//SYSULMOD DD DSNAME=PVTLIB, DISP=OLD, UNIT=5350, 
17 VOLUME=SER=PVT002 
x 


“7SYSLIN DD 


Object Deck for READ 
Object Deck for WRITE 


ENTRY READIN 
INCLUDE SYSLMODCINOUT) 
NAME INOUTCR) 

7% 
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Example 2 


The output load module contains the new READ control section, 
the new WRITE control section (replacing the old WRITE control 

radehea tre member INOQUT), and all remaining control sections 
rom ; 


A large load module named PAYROLL, originally written in COBOL, 
contains many control sections. Two control sections, FICA and 
STATETAX, were recompiled and passed to the linkage editor job 
step in the &&OBJECT data set. Then, by including the load 
module PAYROLL Ca member of the partitioned data set LIB001) as 
well as the output of the language translator, the modified 
control sections automatically replace the identically named 
control sections (Figure 29 on page 98). 


//SYSLMOD DD DSNAME=LIBOO2CPAYROLL), DISP=OLD, 
// UNIT=3350,VOLUME=SER=LIBO02 
//SYSLIB DD DSNAME=SYS$1.COBLIB,DISP=SHR 
/7OLDLOAD DD DSNAME=LIB001,DISP=(OLD, DELETE), 
UNIT=33550, VOLUME=SER=LIBOO1 


47 
77SYSLIN AD DSNAME=&& OBJECT, DISP=COLD, DELETE) 
17 


D xX 
INCLUDE OLDLOADCPAYROLL) 
ENTRY INITI 
7% 
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Input Modules - JCL and Control Statements | Output Load Module 


&& OBJECT 


FICA 
(new) LIBOO2 
| (Payroll) 
STATETAX 
(new) 


LIBOO! | : 
(Payroll) //SYSLMOD DD DSNAME=LIBOO2(PAYROLL),... 


//OLDLOAD DD DSNAME=LIBOO1,... 







FICA 
(new) 








STATETAX 
(new) 


’ 
MAINROUT //SYSLIN DD DSNAME=&&OBJECT,... 
; // DD * MAINROUT 
INCLUDE OLDLOAD(PAYROLL) 
OVERTIME ENTRY INITL 
ys OVERTIME 


FICA 
(old) FEDTAX 
STATETAX 
(old) ILLACC 
FEDTAX 
VAKTION 


ILLACC 





VAKTION 


a a ee 





Figure 29. Automatic Replacement of Control Sections 


The output module contains the modified FICA and STATETAX 
control sections and the rest of the control sections from the 
old PAYROLL module. The main entry point is INITL, and the 
output module is placed ina library named LIBO02. The COBOL 
automatic call library is used to resolve any external 
references that may be unresolved after the SYSLIN data sets are 
processed. 


REPLACE STATEMENT 


The REPLACE statement is used to replace control sections when 
the old and the new control sections have different names. The 
name of the old control section appears first, followed by the 
name of the new control section in parentheses. The REPLACE 
statement must precede either the input module that contains the 
control section to be replaced, or the INCLUDE statement that 
specifies the input module. The scope of the REPLACE statement 
1s across the immediately following module Cobject module or 
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load module). The END record in the immediately following 
object module or the end-of-module indication in the load module 
terminates the action of the REPLACE statement. 


An external reference to the old control section from within the 
same input module is resolved to the new control section. An 
external reference to the old control section from any other 
module becomes an unresolved external reference unless one of 
the following occurs: 


@ The external reference to the old control section is changed 
be ee Ait control section with a separate CHANGE control | 
statement. 


e The same entry name appears in the new control section or in 
some other control section in the linkage editor input. 


In the following example, the REPLACE statement is used to 
replace one control section with another of a different name. 
Assume that the old control section SEARCH is in library member 
TBLESRCH, and that the new control section BINSRCH is in the 
data set &&0BJECT, which was passed from a previous step 
(Figure 30 on page 100). 


“//7SYSLMOD DD DSNAME=SRCHRTN, DISP=OLD,UNIT=3350, 
// VOLUME=SER=SRCHLIB 

“/7SYSLIN DD DSNAME=&&0BJECT, DISP=COLD, DELETE) 
47 xX 


DD 
ENTRY READIN 
REPLACE  SEARCHCBINSRCH) 
INCLUDE SYSLMODCTBLESRCH) 
NAME TBLESRCHCR) 
7% 
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Input Modules 7 


&&OBJECT 


TE A 
BINSRCH - 


TBLESRCH 







READIN ENTRY 





CALL SEARCH 


SEARCH ‘ 


Figure 30. 


0 


JCL and Control Statements 


Output Load Module 


/ /SYSLMOD DD DSNAME=SRCHRTN.... 


—»//SYSLIN DD  DSNAME=&&OBJECT.... 
Ld, db * TBLESRCH 
ENTRY READIN 
REPLACE SEARCH (BINSEARCH) SEDI ENTRY 
INCLUDE  SYSLMOD(TBLESRCH) 
NAME TBLESRCH (R) 
j= CALL BINSRCH 


BINSRCH 





Replacing a Control Section with the REPLACE Control Statement 


The output module contains BINSRCH instead of SEARCH; any 
references to SEARCH within the module refer to BINSRCH. Any 
external references to SEARCH from other modules will not be 
resolved to BINSRCH. 


SE ON _O 


The REPLACE statement can be used to delete a control section or 


an entry name. The REPLACE statement must immediately precede 
either the module that contains the control section or entry 
name to be deleted or the INCLUDE statement that specifies the 
module. Only one symbol appears on the REPLACE statement; the 
appropriate deletion is made depending on how the symbol is 
defined in the module. 


If the symbol is a control section name, the entire control 
section is deleted. The control section name is deleted from 
the external symbol dictionary only if no address constants 
refer to the name from within the same input module. If an 
address constant does refer to it, the control section name is 
changed to an external record. 


The preceding is also true of an entry name to be deleted. Any 
references to it from within the input module cause the entry 
name to be changed to an external reference. 


These editor-supplied external references, unless resolved with 
other input modules, cause the automatic library call mechanism 
to attempt to resolve them. Also, the deletion of a control 
section or an entry name may cause external references from 
other input modules to be unresolved. Either condition can 
cause the output load module to be marked not executable. 
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eo 


Recas 


Fa 





Input Module 


CODEROUT 


ENCODE 


DECODF 


Figure 3l. 








If a deleted control section contains an unresolved external 
reference, the reference remains. 


If a REPLACE statement, used to delete a CSECT, is the last 
control statement and there are external references to be 
resolved from SYSLIB, the delete request operates on the first 
module from SYSLIB and deletes it. The external reference 
remains unresolved. 


Note: When a control section is deleted, any CSECT 
eee eee data associated with that control Section. is also 
deleted 


In the following example, control section CODER is to be deleted 
CFigure 31). 


“/SYSLMOD DSNAME=PVTLIB, DISP=OLD,UNIT=3350, 
// VOLUME=SER=PVT002 


S/SYSLIN 
ENTRY 
REPLACE DER 
INCLUDE SYSLMODCCODEROUT ) 
NAME CODEROUTCR) 
/* 















JCL and Control Statements Output Load Module 
——<—<—T—wsss 
J /SYSLMOD DD DSNAME=PVTLIB,... 
Jf /SYSLIN DD * a 
ENTRY START 1 
REPLACE CODER 
INCLUDE SYSLMOD( CODEROUT ) 
— NAME CODEROUT(R ) 
/ * 





DECODE 





Deleting a Control Section 


The control section CODER is deleted. If no address constants 
refer to CODER from other control sections in the module, the 
control section name is also deleted. If address constants 

refer to CODER, the name is retained as an external reference. 
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The sequence of control sections or named common areas in an 
aban ia module can be specified by using the ORDER control 
statement. 


Individual control sections or named common areas are arranged 
in the output load module according to the sequence in which 
they appear on the ORDER control statement. Multiple ORDER 
control statements can be used in a job step. The sequence of 
the ORDER statements determines the sequence of the control 
sections or named common areas in the load module. 


Any control sections or named common areas that are not 
specified on ORDER statements appear last in the output load 
module. If a control section or named common area is changed by 
a CHANGE or REPLACE control statement, the new name must be used 
on the ORDER statement. 


In the following example, ORDER statements are used to specify 
the sequence of five of the six control sections in an output 
load module. A REPLACE statement is used to replace the old 
control section, SESECTA, with the new control section, CSECTA, 
from the data set &&0BJECT, which was passed from a previous 
step. Assume that the control sections to be ordered are found 
in library member MAINROOT (Figure 32 on page 1903). 


S/SYSLMOD DSNAME=PVTLIB,DISP=OLD, 
// UNIT=3350, VOLUME=SER=PVT002 
“/SYSLIN DSNAME=&& OBJECT, DISP=COLD, DELETE) 
7/7 X 

ORDER MAINEP, SEGMT1,SEG2 


SESECTACCSECTA) 
CSECTA,CSECTB 
SYSLMODCMAINROOT ) 
MAINROOT 
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&& OBJECT 

, TS — 
Ts 

CSECTA OK 
MAINEP 

// EXEC PGM=HEWL 
SEGMTI 
MAINROOT ° 






//SYSLMOD DD DSNAME=PVTLIB,... 


CSECTB SEG2 









//SYSLIN DD DSNAME=&&OBJECT,... 
SESECTA // DD * CSECTA 
ORDER MAINEP (P) ,SEGMT1 ,SEG2 
MAINEP REPLACE SESECTA (CSECTA) ETS 
ORDER CSECTA,CSECTA ,CSECTB (P) 
INCLUDE SYSLMOD (MAINROOT) 
LASTEP NAME MAINROOT LASTEP 
/* 
_ f at 
( Figure 32. Ordering Control Sections 


In the load module MAINROOT, the control sections MAINEP, 
SEGMT1, SEG2, CSECTA, and CSECTB are rearranged in the output 
load module according to the sequence specified in the ORDER 
statements. A REPLACE statement is used to replace control 
section SESECTA with control section CSECTA from data set 
&&O0BJECT, which was passed from a previous step. The ORDER 
statement refers to the new control section CSECTA. Control 
section LASTEP appears after the other control sections in the 
output load module, because it was not included in the ORDER 
statement operands. 


-L.GNING CONTROL ECTIONS OR NAMED OMMON AREAS ON PAGE BOUNDAR 


ge 


A control section or named common area can be placed on a page 
boundary (to effect a lower paging rate and thus make more 
efficient use of real storage) by using either the ORDER 
statement or the PAGE statement. 


The control section or common area to be aligned is named on 
either the PAGE statement or the ORDER statement with the P 
operand. Either the PAGE statement or the ORDER statement (with 
the P operand) causes the linkage editor to locate the starting 
address of the control section or common area on a page boundary 
within the load module. 


In the following example, the control sections RAREUSE and 
| MAINRT are aligned on page boundaries by PAGE and ORDER control 
a statements. Control sections MAINRT, CSECTA, and SESECT1 are 
nee sequenced by the ORDER control statement. Assume that each 
control section, except for SESECT1 and RAREUSE, is 4K bytes in 
length (Figure 22). 
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//LKED EXEC PGM=HEWL,PARM="...* | fs 


//SYSLMOD ~—s DDD DSNAME=OWNLIB, DISP=OLD, UNIT=3350, 
- VOLUME=SER=OWN002 
X 


17 

S/SYSLIN DD 
PAGE RAREUSE | 
ORDER MAINRTCP),CSECTA,SESECT1 
INCLUDE SYSLMOD (CMAINROOT) 
NAME MAINROOT 





Input Module JCL and Controls Statements Output Load Module 


MAINROOT MAINROOT 


MAINRT 


CSECTA 


SESECT 1 
RAREUSF 


BOTTOM 


The linkage editor places the control sections MAINRT and 
RAREUSE on page boundaries. Control sections MAINRT, CSECTA, 
and SESECT1 are sequenced as specified in the ORDER statement. 
RAREUSE, while placed on a page boundary, appears after the 
control sections specified in the ORDER statement because it was 
not included. The control section BOTTOM comes after RAREUSE 
because it appeared after RAREUSE in the input module. 





CSECTA 





/ /UKED EXEC PGM=HEWL 


i Se a 


4K 


RAREUSE 


//SYSLMOD DD DSNAME=OWNLIB,... 

SESECTI //SYSLIN DD * 

PAGE RAREUSE 8K 
BOTTOM ORDER MAINRT(P) ,CSECTA,SESECT1 
INCLUDE SYSLMOD (MAINROOT) 


. NAME MAINROOT 
7 12K 






MAINRT 





Figure 33. Aligning Control Sections on Page Boundaries 


co 
eS 
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The linkage editor can be invoked by a problem program at 
execution time through the use of one of the following macro 
instructions. | 


Csymbol ] CLINK] 


PARAM=(optionlistl,ddname list])> 
VL=1 i a 


ECsymbol ] CLATTACH] 








femiorr [ens | erintedtiome 


EP= 
specifies the symbolic name of the linkage editor. The 
entry point at which execution is to begin is determined 
by the control program (from the library directory entry). 
Any of the symbolic names that can be used as operands of 
the EXEC command's PGM parameter are acceptable as the 
"linkeditname". 


PARAM=(optionlistl»ddname list] ) 
specifies, as a sublist, address parameters to be passed 
from the problem program to the linkage editor. The first 
fullword in the address parameter list contains the 
address of the option and attribute list for the load 
module. The second fullword contains the address of the 
ddname list. If standard ddnames are to be used, this 
list may be omitted. | 


specifies the address of a variable-length list 
containing the options and attributes. This address 
must be written even though no list is provided. 


The option list must begin on a halfword boundary. 
The 2 high-order bytes contain a count of the number 
of bytes in the remainder of the list. If no options 
or attributes are specified, the count must be zero. 
The option list is free form, with each field 
separated by a comma. No blanks or zeros should 
appear in the list. 


specifies the address of a variable-length list 
containing alternative ddnames for the data sets used 
during linkage editor processing. If standard 
ddnames are used, this operand may be omitted. 
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The ddname list must begin on a halfword boundary. 

The 2 high-order bytes contain a count of the number om, 
of bytes in the remainder of the list. Each name of (A : 
less than 8 bytes must be left justified and padded Ng! 
with blanks. If an alternate ddname is omitted from 

the list, the standard name will be assumed. If the 

name is omitted within the list, the 8&-byte entry 

must contain binary zeros. Names can be omitted from 

the end by merely shortening the list. 





The sequence of the 8&-byte entries in the ddname list 
is as follows: 


Alternate Name For: 
SYSLIN 















Member name (the name under 
which the output load module 
is stored in the SYSLMOD data 
set; this entry is used if the 


name is not specified on the 
SYSLMOD DD statement or if 
there is no NAME control 
statement) 


Entry 
a 
3 systmop 
Lael 
a 
oa! 
p12 








specifies that the sign bit is to be set to 1 in the last 
fullword of the address parameter list. 


When the linkage editor completes processing, a condition code 
is returned in register 15 (see Figure 16 on page 53 for a list 
of linkage editor return codes). 


va 
Le # 


‘ 
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The linkage editor produces two types of output: a load module 
and diagnostic information. The principal output of the 
linkage editor is the output load module. The linkage editor 
always places this load module ina partitioned data set. In 
addition, the linkage editor issues diagnostic information. 
Error and/or warning messages, module disposition data, and 

oe ecte, diagnostic output are stored in the diagnostic output 
ata set. 


The linkage editor produces one or more load modules (see "™ 
Load Module Format" on page 118) from the input processed. 

sabes more than one load module is produced, the process is 

calle ; 


Whether or not the linkage editor produces one or more load 
modules, the following apply: 


® ane load module is stored in a partitioned data set called 
e : 


e The load module must have an entry point; if the programmer 
has not assigned one, the linkage editor does. 


® The output load module is assigned an authorization code. 


° During processing, the linkage editor reserves and collects 
( common areas, as specified in the source language program. 


e During processing, the linkage editor accumulates total 
length and individual displacements for each pseudoregister 
(external dummy section). 


e During processing, the linkage editor collects and records 
ae ern data in the CSECT identification CIDR) 
records. 


@ During the processing of a load module, the linkage editor 
deletes any private code Cunnamed control section) having a 
ries of zero and any identification data associated with 
it. 


® The main entry point, each true alias, and each alternate 
entry point are assigned an addressing mode (CAMODE). 


e The output load module is assigned a residence mode 
CRMODE). 


OUTPUT MODULE LIBRARY 


The linkage editor stores every load module it produces in the 
output module library. This library is a partitioned data set 
that must be described by a DD statement with the name SYSLMOD. 
The data set name of the library is also specified on this DD 
statement. The data set can be either temporary (defined with 
a double ampersand), or permanent (defined with a single or no 
ampersand). If the data set name is either SYS]1.LINKLIB or 
SYS1.SVCLIB, it would be advisable to re-IPL the system after 
linkage editor processing is complete. This ensures that the 
corresponding data extent block CDEB) is updated to reflect 
additional extents if secondary allocation of direct-access 
space was required. 





Whether the data set is permanent or temporary, each module 
must be assigned a unique name, called the member name, to 
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distinguish one load module from another. The output module 
can be assigned aliases if the programmer wants the module 
either identified by more than one name or entered for 
execution at several different points. Each member name and 
alias in a load module library must be unique. The library 
member name and aliases for each load module appear as separate 
entries in the library directory, along with the module 
attributes. (Some module attributes can be assigned on the 
EXEC statement for each linkage editor job step; see "Module 
Attributes™ on page 37.) 


The member name of the output load module may be specified on 


the SYSLMOD DD statement, in a NAME statement, or both. If the 
member name is not specified, the default is TEMPNAME. If this 
default name has been previously assigned to a load module, 
using it again will cause a failure. 


ASSIGNED ON SYSLMOD DD STATEMENT: If the member name is 
assigned on the SYSLMOD DD statement, the name is written in 
oe eee following the data set name of the library. For 
example: 


//SYSLMOD DD DSNAME=MATHLIBCSQDEV), DISP=C(NEW, KEEP), 
47 


UNIT=3350,SPACE=(TRK,(100,10,1)), 
// VOLUME=SER=LIBO02 





The member name SQDEV is assigned to the load module, which is 
placed in the new library named MATHLIB. 


ASSIGNED ON NAME CONTROL STATEMENT: If the member name is not 
specified on the SYSLMOD DD statement, it may be assigned in a 
NAME control statement. For example: 


//SYSLMOD DD DSNAME=MATHLIB, DISP=CNEW,KEEP),... 


//SYSLIN DD DSNAME= &&0BJECT, DISP=COLD, DELETE),... 
x 


DD 
SQDEV 





The member name SQDEV is assigned to the load module, which is 
placed in the library named MATHLIB. 


ASSIGNED ON BOTH: If both the SYSLMOD DD statement and the 
NAME control statement specify a member name, the names should 
be identical. If the names are different, the name on the NAME 


‘control statement is used as the member name. 


Note: If a "link-edit and go" sequence of job steps is 
performed and the program name in the EXEC statement of the 
"go" step contains a backward reference to the SYSLMOD DD 
statement in the "link-edit"™ step, the user must ensure that 
the member name specified in the SYSLMOD DD statement is valid 
and is not overridden by a NAME control statement. 
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Alias Names 








An example of an error: 


//7LKED EXEC PGM=HEWL 


//SVSLMOD DD ca ada i dae 

17 Poes 

/7SYSLIN DD DSNAME=&&OBJECT, DISP=COLD, DELETE),... 
47 ¥ 


DD 
READ 


EXEC PGM=%.LKED.SYSLMOD 


Remember, this example is incorrect! 





The EXEC statement of the GO step specifies that the module to 


be executed is described in the LKED step in the SYSLMOD 
statement. The system tries to locate a member named GO; 
however, the output module was assigned the name READ 


REPLACING AN IDENTICALLY NAMED LIBRARY MEMBER: The output 
module can replace an identically named member in the library 
in either of two ways. The SYSLMOD DD statement names an 
existing data set, as follows: | 


//7SYSLMOD DD DSNAME=MATHLIBCSQDEV),DISP=COLD, 
// KEEP 


Pees 





Or, the NAME control statement specifies the replace function, 
as follows: 


NAME SQDEVCR) | 


In either case, the member named SQDEV is replaced with a new 
module of the same name. 





An output module can be assigned a maximum of 16 aliases, 
specified with the ALIAS control statement. The aliases exist 
in addition to the member name of the output module. When a 
module is referred to by an alias, execution begins at the 
external name specified by the alias. If the name specified by 
the ALIAS statement is not an external symbol within the 
module, the main entry point is used. 


For example, an output module is to be assigned two additional 
entry points, CODE] and CODE2. In addition, because of a 
misunderstanding, calling modules have been written and tested 
using both ROUTONE and ROUT] to refer to the output module. 
Rather than correct the calling modules, an alternate library 
member name Calias) is also assigned. 
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//SYSLMOD DD DSNAME=PVTLIB, DISP=OLD,UNIT=3350, 
// VOLUME=SER=LIBOO1 

//SYSLIN BD DSNAME=&& OBJECT, DISP=COLD, DELETE) 
47 





D % 
ALIAS CODE1 , CODEZ, ROUTONE 
NAME ROUTI1 
/% 





The names CODE], CODE2, and ROUTONE appear in the library 
directory along with ROUT1, the member name. Because CODE] and 
CODE2 are defined as external symbols within the output module, 
when these names are used, execution begins at these points. 
Control may be passed to the main entry point by using either 
the member name ROUTI1 or the alias ROUTONE. 


ENTRY POINT 


Every load module must have a main entry point. The programmer 
may specify the entry point in one of two ways: 


e On a linkage editor ENTRY control statement. 


8 On an Assembler language END statement, which is the last 
statement in the source program. The assembler produces an 
object module and an END statement for the module. The 
assembler-produced END statement contains an entry point 
only if the source language END statement contained one. 


From its input, the linkage editor selects the entry point for 
the load module as follows: 


1. From the first ENTRY control statement in the input. Mgt 


2. If there is no ENTRY control statement in the input, from 
the first assembler-produced END statement that specifies 
an entry point. 


3. If no ENTRY control statement or no assembler-produced END 
statement specifies an entry point, the first byte of the 
first control section of the load module is used as the 
entry point. 


In general, the entry point should be explicitly specified, 
because it is not always possible to predict which control 
section will be first in the output module. 


When a load module is reprocessed by the linkage editor, it has 
no END statement. Therefore, if the first byte of the first 
control section of the load module is not a suitable entry 
point, the entry point must be specified in one of two ways: 


e Through an ENTRY control statement. 


e Through the assembler-produced END statement of another 
input module, which is being processed for the first time. 
This object module must be the first such module to be 
processed by the linkage editor. 


An entry point other than the main entry point may be specified 
with an ALIAS control statement. The symbol specified on the 
ALIAS statement must be defined as an external symbol in the 
load module. Any reference to that symbol causes execution of 
the module to begin at that point instead of at the main entry 
point. 

In the following example, assume that CDCHECK, CODE], and CODE2 & y 
are defined as external symbols in the output module. 


110 MVS/XA Linkage Editor and Loader User's Guide 














//SYSLIN aD DSNAME=&&0BJECT, DISP=COLD, DELETE) 
47 3 
ENTRY CDCHECK 


ALIAS CODE1,CODE2,ROUTONE 
NAME ROUT] 
FR 





As a result of the preceding control statements, CDCHECK is the 
main entry point; CODE] and CODE2 are additional entry points. 
Any reference to ROUTONE or ROUT1 causes execution to begin at 
CDCHECK; any reference to CODE] and CODE2 causes execution to 
begin at these points. 


Authorization Code 


Each load module link-edited is assigned an authorization code 
that determines whether or not the module is allowed to use 
restricted system services and resources. A nonzero code 
allows the module to use restricted services and resources; a 
zero code disallows that usage. The authorization code becomes 
part of the directory entry for the module in the library 
containing the module. 


Residence and Addressing Modes 


Each entry in the library directory for the output load module 
Cone for the main entry point and one for each true alias or 
alternate entry point) contains an indication of the residence 
ga mode for the load module and an indication of the addressing 
( mode for that entry point. The entries for true aliases and 
alternate entry points also contain an indication of the 
addressing mode for the main entry point. 


RESERVING STORAGE IN THE OUTPUT LOAD MODULE 


In FORTRAN, Assembler language, and PL/I, the programmer can 
create control sections that reserve virtual storage areas that 
contain no data or instructions. These control sections are 
called "common" or "static external™ areas, and are produced in 
the object modules by the language translators. These common 
areas are used, for example, as communication regions for 
different parts of a program or to reserve virtual storage 
areas for data supplied at execution time. These common areas 
are either named or unnamed (blank). 


COLLECTION OF COMMON AREAS: During processing, the linkage 
editor collects common areas. That is, if two or more blank 
common areas are found in the input, the largest blank common 
area is used in the output module; all references to a blank 
common area refer to the one retained. If two or more named 
common areas have the same name, the largest of the identically 
named common areas is used in the output module; all references 
to the named common areas refer to the one area retained. 


IDENTICALLY NAMED COMMON AREAS AND CONTROL SECTIONS: Ifa 
control section (as is generated from a BLOCK DATA subprogram 
in FORTRAN, for example) and a named common area have the same 
name, the length of the control section must be greater than or 
equal to the length of the named common area. If the control 
section is smaller in length than the named common area, a 
diagnostic message is issued. The control section is regarded 
as the largest of the common areas processed with that name. 
All subsequent control sections and/or common areas with the 
same name are ignored. 
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PROCESSING PSEUDOREGISTERS 


In PL/I, programmers can use pseudoregisters to define storage 
that will not be reserved in the load module but can be 
allocated dynamically during execution. The external dummy 
sections generated by Assembler H Version 2 correspond to the 
pseudoregisters of PL/I. 





The linkage editor accumulates the total length of all 
pseudoregisters in the input and records the displacement of 
each. If two or more pseudoregisters have the same name, the 
one with the longest length and the most restrictive alignment 
will be retained. All other pseudoregisters with the same name 
will be ignored; all references to the identically hemes 
pseudoregisters will refer to the one retained. 


MULTIPLE LOAD MODULE PROCESSING 


The linkage editor can produce more than one load module in a 
single job step. A NAME control statement in the input stream 
is used as a delimiter for input to a load module. If 
additional input modules follow the NAME statement in the input 
stream, they are used in the formation of the next load module. 


Each load module that is formed has a unique name and is placed 
in the same library as a separate member. When processing 
multiple load modules in a single job step, the options and 
attributes specified in the EXEC statement for that job step 
apply to all load modules created. If the linkage editor 
terminates abnormally during processing of any of the output | 
modules, neither that module nor any of the modules yet to be 
processed in the job step is processed or placed in the 
library. Load modules processed before abnormal termination 
have already been placed in the library. 


In the following example, two load modules are produced in one | 
linkage editor job step: re 


//LKED EXEC PGM=HEWL,PARM="MAP,LIST' 


//7SYSLMOD ) DSNAME=PAYROLL COVERTIME), DISP=OLD, 
//  UNIT=3350,VOLUME=SER=LIBO02 


//MODTWO DD DSNAME=&&0BJECT, DISP=COLD, DELETED 
S/SYSLIN BD DSNAME=S&OBJECTCA), DISP=C(OLD, DELETE) 
x 

INIT 

OVERTIME 

MODTWOCB) 

HSKEEP 

VACATION 





The first load module is produced from the object module in the 
data set defined on the SYSLIN DD statement. The main entry 
point is INIT and the member name is OVERTIME. 


The second load module is produced from the object module 
specified by the INCLUDE statement. The main entry point is 
HSKEEP and the member name is VACATION. 


hewucr., of83" 
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If an INCLUDE statement specifies a member name that is 
different from the member name on the DD statement, the member 
specified on the DD statement must exist even though it is not 
to be included. 


Both load modules are placed in the library PAYROLL, defined on 
the SYSLMOD statement. 


The parameters on the EXEC card specify that a module map and a 
control statement listing are produced for each load module. 
UN and listing are discussed in detail in the next 
section. 


Diagnostic information is stored in the diagnostic output data 
set, which must be defined by a DD statement with the name 
SYSPRINT. This output is a collection of messages generated by 
the linkage editor, as well as any optional output requested by 
the programmer. 


The linkage editor generates two types of messages: module 
disposition messages and error/warning messages. Descriptions 
of the error/warning messages will be found in 


Module Disposition Messages 


Module disposition messages of several types are printed for 
each load module produced. The first message indicates the 
options and attributes specified for each module. Invalid 
options or attributes are replaced by INVALID in the output. 
Messages are also generated to inform the programmer that 
incompatible attributes have been specified. 


Disposition messages also describe the handling of the load 
module. These messages are preceded by several asterisks, and 
are: 


° member name NOW ADDED TO DATE SET. 
e member name NOW REPLACED IN DATA SET. 
e member name DOES NOT EXIST BUT HAS BEEN ADDED TO THE DATA 


The replacement function was specified, but the member did 
not exist in the data set; the module is added to the data 
set using the member name given. 


e alias name IS AN ALIAS FOR THIS MEMBER. 
e MODULE HAS BEEN MARKED NOT EXECUTABLE. 


In addition, module disposition messages are used when the 
reenterable (RENT), reusable CREUS), and/or refreshable CREFR) 
linkage editor options have been specified for the module. 

When one or more of these module attributes have been 
indicated, a message informs the user what attribute Cs) have 
been assigned to the module. This message indicates whether 
the load module has been marked reenterable or not reenterable, 


reusable or not reusable, refreshable or not refreshable, 


depending on the option or options used. (See "Reusability 
Attributes™ on page 39 and "Refreshable Attribute" on page 40 
for more information on these options. ) 
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The message consists of several asterisks and MODULE HAS BEEN 
MARKED, followed by the attribute(s) assigned as a result of 


the linkage editor options specified. The programmer, of 
course, is responsible for verifying that the module actually 
is reenterable, reusable, and/or refreshable. The following 
messages are examples of some possible combinations: 

e MODULE HAS BEEN MARKED REFRESHABLE. 

® MODULE HAS BEEN MARKED NOT REFRESHABLE. 

e MODULE HAS BEEN MARKED REUSABLE AND NOT REFRESHABLE. 

@ MODULE HAS BEEN MARKED REUSABLE AND REFRESHABLE. 

When an error causes the linkage editor to mark a module not 


executable, only the MODULE HAS BEEN MARKED NOT EXECUTABLE 
message appears; no attribute messages are generated. 


Error/Warning Messages 


Certain conditions that are present when a module is being 
processed can cause an error or warning message to be printed. 
These messages contain a message code and message text. If an 
error is encountered during processing, the message code for 
that error is printed with the applicable symbol or record in 
error. After processing is completed, the diagnostic message 
associated with that code is printed. The error warning 
messages have the following format: 


IEWOmms message text 

where: 

ITEWO indicates a linkage editor message 
iim is the message number 


Ss is the severity code, and may be one of the following 
values: 


1 Indicates a condition that may cause an 
error during execution of the output 
module. A module map or cross-reference 
table is produced if specified by the 
programmer. The output module is marked 
executable. 


2 Indicates an error that could make 
execution of the output module impossible. 
Processing continues. When possible, a 
module map or a cross-reference table is 
produced if specified by the programmer. 
The output module is marked not executable, 
unless the LET option is specified on the 
EXEC statement. 


3 Indicates an error that will make execution 
of the output module impossible. Processing 
continues. When possible, a module map or 
a cross-reference table is produced if 
specified by the programmer. The output 
module is marked not executable. 


& Indicates an error condition from which no 
recovery is possible. Processing 
terminates. The only output is diagnostic 
messages. 


Note: <A special severity code of zero is generated for each 
control statement printed as a result of the LIST option. 
Severity zero does not indicate an error warning condition. 
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The highest severity code encountered during processing is 
multiplied by 4 to create a return code that is placed in 
register 15 at the end of processing. This return code can be 
tested to determine whether or not processing is to continue 
(see "EXEC Statement—Return Code™ on page 53). 


message text contains combinations of the following: 





e The message classification Ceither error or warning) 


e Cause of error 





e Identification of the symbol, segment number Cwhen in 
overlay), or input item to which the message applies 


e Instructions to the programmer 





® Action taken by the linkage editor 


Optionally, error/warning messages can be sent to a separate 
output data set, which is defined by specifying TERM in the 
PARM field of the EXEC statement and including a SYSTERM DD 
statement. This separate SYSTERM data set consists of only 
numbered error/warning messages. It supplements the SYSPRINT 
output data set, which can also include module disposition 
messages and optional diagnostic output. When SYSTERM is used, 
the numbered error/warning messages appear in both data sets. 


: contains a complete list of error/warning 
messages. 


Sample Diagnostic Output 


Figure 34 on page 116 shows the format of the diagnostic output 
Piss for the linkage editor. No optional output was requested other 
( than the list of control statements. 


The letters indicate the disposition and error/warning messages 
as follows: 


A Is a module disposition message that lists the 
options and attributes specified. Additional 
information is printed indicating the variable and 
default options used. 


B Is a list of control statements used (CIEW0000) and 
the message codes (CIEW0201 and IEW0461) for 
error/warning conditions discovered during 
processing. For error/warning message codes, the 


symbol in error, if necessary, is also listed 
CCCCCCCCC and BASEDUMP). 


Cc Is a module disposition message (¥*¥X*%) that indicates 
that the output module CBBBBBBBB) has been added to 
the output module data set. 


D Is the diagnostic message directory that contains the 
text of the error codes listed in item B ; 
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| A F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED LET,NCAL, XREF,OVLY,LIST 
DEFAULT OPTIONS (S) USED - SIZE=(65536,6144) 
B IEwWO000 NAME BBBBBBBB . 
LEWO201 : 
IEWO461 CCCCCCCC 
IEWO461 BASECUMP 
C ****BBBBBBBB NOW ADDED TO DATA SET 
DIAGNOSTIC MESSAGE DIRECTORY 
D IEW0201 WARNING - OVERLAY STRUCTURE CONTAINS ONLY ONE SEGMENT -- OVERLY OPTION 
CANCELED. 
IEWO461 WARNING - SYMBOL PRINTED IS AN UNRESOLVED EXTERNAL REFERENCE, NCAL WAS 
SPECIFIED. 
| | e e e e e 
| Figure 34. Diagnostic Messages Issued by the Linkage Editor 
Module Map 


If the MAP option is specified on the EXEC statement, a module 
map of the output load module is produced. The module map 
shows all control sections in the output module and all entry 
names in each control section. Named common areas are listed 
as control sections. 


For each control section, the module map indicates its origin 
Crelative to zero) and length in bytes (Cin hexadecimal 
notation). For each entry name in each control section, the 
module map indicates the location at which the name is defined. 
These locations are also relative to zero. 


If the module is not in an overlay structure, the control 
sections are arranged in ascending order according to their 
origins. An entry name is listed with the control section in 
which it is defined. 


If the module is an overlay structure, the control sections are 
arranged by segment. The segments are listed as they appear in 
the overlay structure, top to bottom, left to right, and region 
by region. Within each segment, the control sections and their 
corresponding entry names are listed in ascending order 
according to their assigned origins. The number of the segment 
in which they appear is also listed. 
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In any module map, the following are identified by a dollar 





sign: 
® Blank common area 
@ Private code Cunnamed control section) 


e ae era programs, the segment table and each entry 
able 


When the load module processed by the linkage editor does not 
have an origin of zero, the linkage editor generates a one-~byte 
private code Cunnamed control section) as the first text 
record. This private code is deleted in any subsequent 
reprocessing of the load module by the linkage editor. 


Each control section that is obtained from a call library 
during automatic library call is identified Py an asterisk 
after the control section name. 





At the end of the module map is the entry address, that is, the 
relative address of the main entry point. The entry address is 
followed by the total length of the module in bytes; in the 
case of an overlay module, the length is that of the longest 
path. Pseudoregisters, if used, also appear at the end of the 
module map; the name, length, and displacement of each 
pseudoregister are given. 





Figure 35 contains a module map with five control sections. 
There are two named control sections (COBSUB snd MAINMOD), one 
unnamed control section Cdesignated by $PRIVATE), and two 
control sections obtained from a call library CILBODSPO and 
ILBOSTPO0). In addition, two entry names are defined: SUBI1 in 
the unnamed control section and ILBOSTP1 in control section 


CONTROL SECTION ENTRY 
NAME ORIGIN LENCTH NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
COBSUB 00 33A 
S$PRIVATE 340 EF 
SUB1 340 
MAINMOD 430 166 
ILBODSPO* 598 SE2 
ILBOSTPO* B80 35 
ILBOSTP 1 B96 
ENTRY ADDRESS 430 
TOTAL LENGTH BB8 
#***G0 DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 


Figure 35. Module Map 


Cross-Reference Table 


If the XREF option is specified on the EXEC statement, a 
cross-reference table is produced. The cross-reference table 
consists of a module map anda list of cross-references for 
each control section. Each address constant that refers to a 
symbol defined in another control section is listed with its 
assigned location, the symbol referred to, and the name of the 
control section in which the symbol is defined. When control 
sections are compiled together, and simple address constants 
are used to refer from one control section to another Cinstead 
of using external symbols and entry names), the control section 
name is listed as the symbol referred to. 
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For overlay programs, this information is provided for each 
segment; in addition, the number of the segment in which the 
symbol is defined, is provided. 


If a symbol is unresolved after processing by the linkage 
editor, it is identified by S$UNRESOLVED in the list. However, 
if an unresolved symbol is marked by the never-call function 
Cas specified on a LIBRARY control statement), it is identified 
by $NEVER-CALL. If an unresolved symbol is a weak external 
reference, it is identified by S$UNRESOLVEDCW). 


Figure 36 contains a cross-reference table for the same program 
whose module map is shown in Figure 35 on page 117. All the 
information from the module map is present, plus a list of 
cross-references for each control section. 





CONTROL SECTION 


CROSS=REFERENCE TABLE 


ENTRY 


NAME ORIGIN LENGTH NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
COBSUB 00 33A 
$PRIVATE 340 EF 
SUB1 340 
MAINMOD 430 166 
ILBODSPO* 598 5E2 
ILBOSTPO* B80 35 
ILBOSTP 1 B96 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
250 ILBOSTPO ILBOSTPO 254 ILBODSPO I LBODSPO 
258 ILBOSTP1 ILBOSTPO 450 SUB1 
478 COBSUB COBSUB 
ENTRY ADDRESS 430 
TOTAL LENGTH BB8 


Figure 36. Cross-Reference Table 





The format of a load module built by the linkage editor is 
shown in Figure 37 on page 119. 


In writing the output load module to the SYSLMOD data set, the 
linkage editor does not use the track overflow feature. When 
moving or copying load modules, the track overflow feature must 
not be used on the target data set, as errors may occur in 
fetching the load modules for execution. 
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( TTR-P2, if TEST option and SYM records present 


TTR-P2, if no TEST option 
TTR-T3, if no OVLY option 


TTR-T3, if OVLY option used 
TTR-N/S!, if SCTR 
yortion 


SYM | | CESD | | IDR | | CTL | | SEGTAB | | SCTR | | CTL | | Ist TXT | | ENTAB | (continued) 


f Present if TEST — if OVLY Loon if SCTR , Present if OVLY option 
option is used used and more than | 
segment 


‘option and SYM option and more 


records present than 1 segment 
TTR-N/S!, if OVLY option 


and more than 1 segment 


RLD | CTL,RLD, ...CTL, RLD, TXT, ENTAB | L_RLD | | CTL | | TXT_ | L IIR | 


, Carries EOS if one EOM f Carries EOM f Present if OVLY option 
following ENTAB if thisis RLD if no RLDs and more than | segment 
for Last TXT for Last TXT 


ITTR-N/S: TTR of the note list or scatter/translation table. Used for 
modules in scatter load format or overlay structure only. 


2TTR-P: TTR of the first block of the named member (load module). 


3TTR-T: TTR of the first block of text. 


( Figure 37. Load Module Format 
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Part II. Loader 
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The Loader is a processing program that combines basic editing 
and loading functions of the linkage editor and program fetch 
into one job step. Therefore, the load function is equivalent 
to the link-edit-go function. The loader can be used for 
compile-load and load jobs. 


The loader will load object modules produced by a language 
processor and load modules produced by the linkage editor into 
virtual storage for execution. Optionally, it will search a 
call library CSYSLIB) or a resident link pack area, or both, to 
resolve external references. The loader does not produce load 
modules for program libraries. 


The functional characteristics, compatibility and restrictions, 
performance considerations, and storage considerations of the 
loader are described in the following sections. 


FUNCTIONAL CHARACTERISTICS 


Addressing Mode 


The loader is reenterable and, therefore, can reside in the 
resident link pack area. 


The loader combines the following basic functions of the 
linkage editor and program fetch: 


1. Resolution of external references between program modules. 


2. Optional inclusion of modules from a call library (SYSLIB) 
or from a link pack area, or from both (Figure 38 on 
page 125 and Figure 39 on page 126). (Inclusion of modules 
from a call library or the link pack area is performed, if 
requested, when external references remain unresolved after 
processing the primary input to the loader. If both are 
requested, the link pack area is searched first.) 


3. Automatic deletion of duplicate copies of program modules 
(Figure 40 on page 126). (The first copy is loaded and all 
following requests use that copy. ) 


G. Relocation of all address constants so that control may be 
sais directly to the assigned entry point in virtual 
storage. 


5. The loader can load programs and relocate address constants 
both above and below the 16-megabyte virtual storage line, 
as specified by the residence mode for the loaded program. 
The loader can also provide for entry into the loaded 
program according to a specified addressing mode. 


The addressing mode CAMODE) is the attribute of the entry point 
into the loaded module that specifies the addressing mode that 
a in effect when the module is entered at that entry 
point. 


The valid addressing modes are: 


24 Indicating that 24-bit addressing will be in effect 
ol Indicating that 3l-bit addressing will be in effect 
ANY Indicating that either 24-bit or 3l-bit addressing 


may be in effect 
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The loader determines the addressing mode for the entry point 
as follows: 


The default AMODE of 24 is assumed. 


If the AMODE is specified in the ESD data for the entry 
point, that specification replaces the default, AMODE. 
(This AMODE value was specified by the user as an assembler 
statement.) The loader assigns the AMODE value from the 
control section or private code that contributes to the 
loaded module, ignoring identically named control sections 
and private code, which are replaced. 


If AMODE is specified as a parameter in the PARM field of 
the EXEC statement, that specification replaces the 
previously determined AMODE. 


The residence mode C(CRMODE) is the attribute of the loaded 
module that specifies where in virtual storage the module is to 
be loaded. 

The valid residence modes are: 

24 Indicating that the module must be loaded within 
24-bit addressable virtual storage (below the 
16-megabyte virtual storage line) 

ANY Indicating that the module may be loaded anywhere in 


Virtual storage Ceither above or below the 
16-megabyte virtual storage line) 


The loader determines the residence mode for the loaded program 
as follows: 


The default RMODE of 24 is assumed. 


If the RMODE is specified in the ESD data for the first 
control section or private code which contributes to the 
loaded module, that specification replaces the default 
RMODE. (CThis RMODE value was specified by the user as an 
assembler statement. ) 


If the RMODE is specified as a parameter in the PARM field 
of the EXEC statement, that specification replaces the 
previously determined RMODE. 


If the ESD data for any subsequent control section or 
private code which contributes to the loaded module 
specifies an RMODE of 24, the RMODE for the entire module 
is reset to 24. If loading begins above the 16-megabyte 
virtual storage line on the basis of an early determination 
of RMODE=ANY, and the RMODE is later reset to 24%, an error 
message is issued and loading is restarted below the 
l6-megabyte virtual storage line. 
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AMODE/RMODE Combinations 


The loader validates the combination of the AMODE value and the 
| RMODE value, as specified by the user in the PARM field of the 
EXEC statement, according to the following table: 


If the AMODE/RMODE combination resulting from the PARM field of 
the EXEC statement is invalid, an error message is issued and 


oe loader ignores the PARM field as the source of AMODE/RMODE 
ata. | 













Implied AMODE or RMODE 


If only one value, either AMODE or RMODE, is specified in the 
PARM field of the EXEC statement, the other value is implied 
according to the following table: 


Value Specified Value Implied 
AMODE=ANY RMODE=24 
Tewove=26 | see note 










a 





Note: If only an RMODE of 24 is specified, no overriding AMODE 
value is assigned; instead, the AMODE value in the ESD data for 
the entry point into the loaded module is used. 


The diagnostics produced by the loader are similar to those of 
the linkage editor. 
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Figure 38. Loader Processing-——SYSLIB Resolution 
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Figure 39. Loader Processing~——Link Pack Area and SYSLIB Resolution 















Object and/or 
Load Modules 


The first copy is 
Loader Y A isaded 


SYSLIN Virtual Storage 


Figure 40. Loader Processing——Automatic Editing 





126 MVS/XA Linkage Editor and Loader User's Guide 


























COMPATIBILITY AND RESTRICTIONS 


Time Sharing Option 


The loader accepts the same basic input as the linkage editor: 


1. All object modules that can be processed by the linkage 
editor can be input to the loader. 


2. All load modules produced by the linkage editor can be 
ahh ‘e the loader Cexcept load modules edited with the NE 
option). 


The loader supports the following linkage editor options: MAP, 
LET, NCAL, SIZE, and TERM. All other linkage editor options 
and attributes are not supported, but, if used, they will not 
be considered as errors. A message will be listed on SYSLOUT 
indicating that they are not supported. The supported options 
are specified in the PARM field of the EXEC statement, or with 
the LINK, ATTACH, LOAD, or XCTL macro instruction. In addition 
to the supported linkage editor options, the loader provides 
several other options. All loader options are described under 
"EXEC Statement" on page 128. 


The loader does not process linkage editor control statements 
(for example, INCLUDE, NAME, OVERLAY, etc.). If they are used, 
they will not be treated as errors, and a message will be 
listed on SYSLOUT indicating that the control statements are 
not supported. 


The loader and the linkage editor are bound by the same input 
conventions. (These conventions are discussed in Part 1 of 
this publication.) In addition, the loader can accept load 
modules in the SYSLIN data set and object modules from a data 
area in virtual storage. 


The loader does not use auxiliary storage space for work areas; 
that is, there is no loader function corresponding to the 
linkage editor's creation of intermediate work data sets or 
output load modules. 


(TSO) 


When the loader is used under TSO, it is invoked by the loader 
prompter, a program that acts as an interface between the user 
and the operating system and the loader. Under TSO, execution 
of the loader and definition of the data sets used by the 
loader are described to the system through use of the LOADGO 
command that causes the prompter to be executed. Operands of 
the LOADGO command can also be used to specify the loader 
options a job requires. 


Complete procedures for using the LOADGO command to load and 
execute an object module are given in 


Processing Object Modules in Virtual Storage 


The loader can act as an interface with a compiler that has the 
ability to construct a data area of one or more object modules 
in virtual storage as an alternative to a data set ona 
secondary storage volume (such as a tape or disk). The 
compiler passes the loader a description of the internal data 
area, which the loader then processes as primary input. This 
rhea i data area replaces external SYSLIN data set input to 
e loader. 


Instead of placing text records for the object module in the 
internal data area, the compiler can pass pointers to preloaded 
text. The loader can then perform its relocation and linkage 
functions on the preloaded text itself; text is not moved 
during processing. 


Chapter 9. Overview and Uses of the Loader 127 








This chapter discusses how to prepare an input deck for the 
loader and how to invoke the loader; it also describes the 
output from the loader. 


INPUT FOR THE LOADER 


EXEC STATEMENT 


PARM Field Format 


\ 


The input deck for the loader must contain job control language 
statements for the loader and, optionally, for the loaded 
program (Figure 41). 


//name JOB parameters Coptional) 
//name EXEC PGM=LOADER, | 

PARM=C parameters) 
S/SYSLIN DD parameters 
S/SYSLIB DD parameters Coptional) 
S/SYSLOUT DD parameters Coptional ) 
77SYSTERM DD parameters Coptional ) 
iA Coptional DD statements and data 
17 required for loaded program) 


Figure 41. Input Deck for the Loader-——Basic Format 


Only the EXEC statement and the SYSLIN DD statement are 
required for a loader step. The JOB statement is required if 
the loader is the first step in the job. 


The EXEC statement is used to call the loader and to specify 
options for the loader and the loaded program. The loader is 
called by specifying PGM=HEWLDRGO or PGM=LOADER (see "Chapter 
ll. Invoking The Loader™ on page 138). 


Loader and loaded program options are specified in the PARM 
field of the EXEC statement. The PARM field must have the 
following format: 





Note that the loaded program option(s), if any, must be 
separated from the loader option(s) by a slash (/). If there 
are no loader options, the program option must begin with a 
Slash. The entire PARM field may be omitted if there are no 
loader or loaded program options. 


Parameters must be enclosed in single quotation marks when 
special characters (/ and =) are used. 
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LOADER OPTIONS 


er The loader options are outlined below. Fields that must be 
supplied by the user are underlined; default options are 
_ underlined in boldface type. 


Parameter 


PARM= AMODE=mode| 
CALL | NOCALL 





AMODE=mode: Specifying Address Mode 
Explanation: AMODE=mode is a loader option specifying the 
addressing mode to be in effect when the loaded module is 
entered. Mode can be specified as 24, 31, or ANY 


Abbreviations: None. 





Default: The default addressing mode is 24. 


Restrictions: The addressing mode assigned in the PARM field 
overrides the addressing mode found in the ESD data for the 
control section or private code at which the entry point is 


( located. 


If the AMODE parameter occurs more than once in the PARM field 
of the EXEC statement, the last valid parameter is used. 


CALLINOCALL: Automatically Searching SYSLIB 


Explanation: CALLINOCALL are options specifying whether an 
pete yeh ea of the SYSLIB data set is made when the loader 
is invoked. 


CALL 


Indicates that the SYSLIB data set will automatically be 
searched when the loader is invoked. 


NOCALL 
Indicates that no automatic search of the SYSLIB data set 
is to be made. 
Abbreviations: 
NOCALL INCAL 
Default: The default is CALL. 


Restrictions: f the SYSLIB DD statement is not included in 
the input deck, “he CALLINOCALL option is ignored. 


If the NOCALL option is specified, the NORES option is 
automatically set. 
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EP=name: Specifying the Program Entry Point 


Explanation: EP=name is a loader option that specifies the 
external name to be assigned as the entry point of the loaded 
program. 





Abbreviations: None. 
Default: None. 


Restrictions: EP=name must be specified if the entry point of 
the loaded program is in an input load module. 


For FORTRAN, ALGOL, and PL/I, these entry points must be named 
MAIN, IHIFSAIN, and IHENTRY, respectively, unless changed by 
compiler options. 


LETINOLET: Executing with Severity 2 Errors 


Explanation: LETINOLET are loader options specifying whether 
the loader should try to execute the object program if a 
severity 2 error condition is found. A severity 2 error 
condition is one that could make execution of the loaded 
program impossible. 


LET 
Indicates that the loader will attempt toa execute the 
program even if a severity 2 error is found. 


NOLET 
Indicates that the loader will not attempt to execute the 
program if a severity 2 error is found. 


Abbreviations: None. 
Default: The default is NOLET. 


MAPINOMAP: Printing a Pragram Map 


Explanation: MAP|NOMAP are loader options specifying whether 
to produce a map of the loaded program that lists external 
names and their absolute storage addresses on the SYSLOUT data 
set. The module map is described in "Chapter 12. Interpreting 
Loader Output" on page 143 


MAP 
Indicates that a program map will be printed. 


NOMAP 
Indicates that a program map will not be printed. 


Abbreviations: None. 
Default: The default is NOMAP. 
Restrictions: If the SYSLOUT DD statement is not used in the 
input deck, the MAP|NOMAP option is ignored. 
NAME=name: Identifying the Loaded Program 


Explanation: NAME=name is a loader option specifying the name 
to be used to identify the loaded program to the system. 


Abbreviations: None. 


Default: If this option is not used, the loaded program will 
be named *xXGOQ. 
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PRINTINOPRINT: Printing Messages on SYSLOUT 


ae Explanation: PRINT|INOPRINT are loader options specifying that 
| informational and diagnostic messages are to be produced on the 
SYSLOUT data set. 


PRINT 
Indicates that messages are printed in SYSLOUT. 


NOPRINT 
Indicates that no messages are printed in SYSLOUT. 


Abbreviations: None. 
Default: The default is PRINT. 


Restrictions: If NOPRINT is specified, the SYSLOUT data set is 
not opened. 


RES|INORES: Automatically Searching the Link Pack Area Queue 


Explanation: RESINORES are loader options specifying whether 
an automatic search of the link pack area queue is to be made 
after processing the primary input (CSYSLIN) and before 
searching the SYSLIB data set. 


RES 
Indicates that an automatic search of the link pack area 
queue is to be made. 


NORES 
Indicates that no automatic search of the link pack area 
queue is to be made. 


, Abbreviations: None. 
¢C Default: The default is RES. 


Restrictions: When the RES option is specified, the CALL 
option is also automatically set. 


RMODE=mode: Specifying Residence Mode 


Explanation: RMODE=mode is a loader option specifying the 
residence mode that applies to the loaded module. Mode may be 
specified as 24, 31, or ANY 


Abbreviations: None. 

Default: The default residence mode is 24. 

Restrictions: The residence mode assigned in the PARM field 
overrides the residence mode assigned to the first control 
section or private code. 


If the RMODE parameter occurs more than once in the PARM field 
of the EXEC statement, the last valid parameter is used. 


SIZE=size: Specifying Virtual Storage 
Explanation: SIZE=size is a loader option specifying the 
amount of dynamic virtual storage, in bytes, that can be used 
by the loader. See “Appendix E. Loader Return Codes" on 
page 192 for more information on size. 
Abbreviations: None. 


Default: If this option is not specified, the size defaults to 
300K bytes. 
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TERM|NOTERM: Sending Messages to SYSTERM 


Explanation: TERMINOTERM are loader options specifying whether 
to send numbered diagnostic messages to the SYSTERM data set. 

Although TERM|NOTERM is intended to be used when operating 

under the Time Sharing Option (TSO), the SYSTERM data set can 

eo used to Cnaeoe or. SuPpronent the SYSLOUT data set at any 
ime. 





TERM 


Thdicates that numbered diagnostic messages are sent to 
the SYSTERM oats pat: 


NOTERM 
Indicates that no messages are to be sent to SYSTERM. 


Abbreviations: None. 
Default: The default is NOTERM. 


Restrictions: If the SYSTERM DD statement is not included in 
the input deck, the TERM option is ignored. 


EXEC STATEMENT EXAMPLE 


The following are examples of the EXEC statement. In these 
examples, X and Y are parameters required by the loaded 
program. 


//LOAD PGM=LOADER 

//LOAD | PGM=HEWLDRGO, 

7 PARM="MAP, EP=FIRST/X,Y* 
//LOAD PGM=LOADER, PARM='/X,Y' 


//L OAD PGM=LOADER, PARM=NOPRINT -_ 
//LOAD PGM=LOADER, PARM=C(MAP, LET) | 


//LOAD ) PGM=LOADER, ae 
PARM= "NAME=NEWPROG, TERM, NOPRINT* 
//\L OAD PGM=LOADER, 
7 | PARM=*NAME=NEWMOD, EP=ENTRYZ, 
| AMODE=31,RMODE=ANY' 
47 | 





For further details in coding the EXEC Sra naive? refer to the 
publication 


DD STATEMENTS 


The loader uses four DD statements, named SYSLIN, SYSLIB, 
SYSLOUT, and SYSTERM. The SYSLIN DD statement must be used in 
every loader job. The others are optional. 


The following considerations apply to the DCB parameter of 
SYSLIN, SYSLIB, and SYSLOUT. 


® For better performance, BLKSIZE and BUFNO can be specified. 
° If BUFNO is omitted, BUFNO=2 is assumed. 


e Any value given to BUFNO is assumed for NCP (number of 
channel programs). 


@ If RECFM=U is specified, BUFNO=2 is assumed, and BLKSIZE 
~ and LRECL are ignored. 


©  RECFM=V is not accepted. 
¢ RECFM=FBSA is always assumed for SYSLOUT. 
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SYSLIN DD Statement 





® If RECFM is omitted, RECFM=F is assumed for SYSLIN and 
SYSLIB. | 


® If BLKSIZE is omitted, the value given to LRECL is assumed. 


e LRECL=121 is assumed for SYSLOUT unless the loader is 
operating under the Time Sharing Option (TSO), when 
LRECL=81 is assumed. 


® If LRECL is omitted, LRECL=80 is assumed for SYSLIN and 
SYSLIB. 


e If OPTCD=C is used to specify chained scheduling, and if 
the necessary data management routines are not resident, an 
additional 2K bytes (2048 bytes) of virtual storage is 
needed in the user's region. 


Note: The SYSTERM data set will always consist of unblocked 
8l-character records with BUFNO=2 and RECFM=FSA. Because these 
values are fixed, the DCB parameter need not be used. 


In addition to the DD statements used by the loader, any DD 
statements and data required by the loaded program must be 
included in the input deck. 





The SYSLIN DD statement defines the input data for the loader. 
This input can be either object modules produced by a language 
translator, or load modules produced by the linkage editor, or 
both. The data sets defined by the SYSLIN DD statement can be 
either sequential data sets or members of a partitioned data 
set, or both. The DSNAME parameter for a partitioned data set 
must indicate the member name, that is, 


DSNAME=dsname(membername) . 


Concatenation can be used to include more than one module in 
SYSLIN. 


The following are examples of the SYSLIN DD statement. The 
first example defines a member of a previously cataloged 
partitioned data set: 


“/SYSLIN DD DSNAME=OUTPUT.FORTCMOD12), 
// DISP=OLD, DCB=BLKSIZE=3200 





ie second example defines a sequential data set on magnetic 
ape: 


Z/SYSLIN DD DSNAME=PROG15, UNIT=3400-6,DISP=COLD, 


// KEEP), VOLUME=CPRIVATE, RETAIN, 
17 SER=MCS167) 


The third example defines a data set that was the output of a 
previous step in the same job: 


//SYSLIN DD DSNAME=%.COBOL .SYSLIN, DISP=COLD, 
// DELETE) 


The fourth example shows the concatenation of three data sets. 
The first two data sets are members of different partitioned 
data sets; the first is an object module, and the second is a 
load module. The third data set is in the input stream 
Ueber L, a SYSLIN DD statement (see "Loaded Program Data" on 
page , 


//SYSLIN DD DSNAME=PGMLIB.SETICRFS1),DISP=OLD, 
// DCB=(BLKSIZE=3200, RECFM=FB) 

7 DD DSNAME=PGMLIB.SET2CABC5), DISP=OLD, 
17 DCB=RECFM=U 

/f DD DDNAME=SYSIN 
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SYSLIB DD Statement 


SYSLOUT DD Statement 


SYSTERM DD Statement 


The SYSLIB data set contains IBM-supplied or user-written fi ‘ 
library routines to be included in the loaded program. The eY 
data set is searched when unresolved references remain after . 
processing SYSLIN and optionally searching the link pack area. 


The SYSLIB data set is used to resolve an external reference 
when the following conditions exist: the external reference 
must be (1) a member name or an alias of a module in the data 
set, and (2) defined as an external name in the external symbol 
dictionary of the module with that name. If the unresolved 
external reference is a member name or an alias in the library, 
but is not an external name in that member, the member is 
processed but the external reference remains unresolved unless 
subsequently defined. 


The data set defined by the SYSLIB DD statement must be a 
partitioned data set that contains either object modules or 
load modules, but not both. Concatenation may be used toa 
include more partitioned data sets in SYSLIB. All concatenated 
Seance must contain the same type of modules Cobject or 

oa 


The following are examples of the SYSLIB DD statement. The 
first example defines a cataloged partitioned data set that can 
be shared by other steps: 


//SYSLIB DD DSNAME=SYS1.ALGLIB, DISP=SHR 
The second example shows the concatenation of two data sets: 
/S/SYSLIB DD DSNAME=SYS1.PLILIB, DISP=SHR 
17 DD DSNAME=LIBMOD.MATH, DISP=OLD 


The SYSLOUT DD statement is used for error and warning messages 
and for an optional map of external references (see "Chapter 
12. Interpreting Loader Output” on page 143). The data set 
defined by this DD statement must be a sequential data set. 

The DCB parameter can be used to specify the blocking factor 
CBLKSIZE) of this data set. For better performance, the number 
of ea. CBUFNO) to be allocated to SYSLOUT can also be 
specifie 


The following are examples of the SYSLOUT DD statement. The 
first example specifies the system output unit: 


“/SYSLOUT DD SYSOUT=A 


The second example defines a sequential data set on a 3800 
printer: 


Z/SYSLOUT DD UNIT=3800, DCB=(BLKSIZE=l2l, 
/f BUFNO=4) 


The SYSTERM DD statement defines a data set that is used for 
numbered diagnostic messages only. When the loader is being 
used under the Time Sharing Option (TSO) of the operating 
system, the SYSTERM DD statement defines the terminal output 
data set. However, SYSTERM can also be used at any time to 
replace or supplement the SYSLOUT data set. Because the 
SYSTERM data set is not opened unless the loader must issue a 
diagnostic message, using SYSTERM instead of SYSLOUT can reduce 
loader processing time. 


When the SYSTERM data set replaces the SYSLOUT data set, the 
numbered messages in the SYSTERM data set are the only 
diagnostic output; when SYSTERM supplements the SYSLOUT data 
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set, the numbered messages appear in both data sets, and 
optional diagnostic and informational output, such as a list of 
options or a module map, can be obtained on SYSLOUT. 


The DCB parameters for SYSTERM are fixed and need not be 
specified. The SYSTERM data set always consists of unblocked 
8l-character records with BUFNO=2 and RECFM=FSA. 





The following example shows the SYSTERM DD statement when used 
to specify the system output unit: 


//SYSTERM DD SYSOUT=A 


LOADED PROGRAM DATA 


Loaded program data and loader data can both be specified in 
the input reader. Loaded program data can be defined by a DD 
statement following the loader data. 


Figure 42 shows the loading of a previously compiled FORTRAN 
problem program. The program to be loaded (loader data) 
follows the SYSLIN DD statement. The loaded program data 
follows the FTO5F001 DD statement. 








//LOAD JOB MSGLEVEL=1 

//LDR EXEC PGM=LOADER, PARM=MAP 

S/SYSLIB DD DSNAME=SYS1.FORTLIB, DISP=SHR 
//SYSLOUT DD SYSOUT=A 

//FTO6FO001 DD SYSOUT=A 

S/SYSLIN DD 3 


(Loader data) 


a 7% 
oe //FTO5FO001 DD % 
(Loaded program data) 
7% 


Figure 42. Loader and Loaded Program Data Input Stream 


SAMPLE INPUT FOR THE LOADER 


Figure 43 shows an input deck for a load job. A previously 
assembled program, MASTER, is to be loaded. The SYSLOUT, 
SYSLIB, and SYSTERM DD statements are not used. 


//LOAD JOB MSGLEVEL=1 
4/ EXEC PGM=LOADER 
S/SYSLIN DD DSNAME=MASTER, DISP=OLD 


(DD statements and data required for execution of MASTER) 
7% 


Figure 43. Input Deck for a Load Job 





Figure 44 on page 136 shows an input deck for a compile-load 
job. The OS/VS COBOL CIKFCBLO0) compiler is used for the 
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compile step. The loaded program requires the SYSOUT, TAXRATE, 
and SYSIN DD statements. 





/7I3QB JOB 22,MCS,MSGLEVEL=1 
//COBOL EXEC PGM= IKFCBLOO, PARM=DMAP , REGION=256K,RD= R 
7/7SYSPRINT DD SYSOUT=A 
7/SYSPUNCH DD SYSOUT=B 
//SYSUT1 DD UNIT=SYSDA,SPACE= (TRK,; €100,10)) 
4/SYSUT2 DD UNIT=SYSDA, SPACE=CTRK, (100,10)) 
7/SYSUT3 DD UNIT=SYSDA, SPACE=(TRK, (100,10)). 

— SASYSUTS DD. UNIT=SYSDA, SPACE=CTRK, €100,10)) 
J/¢SYSLIN DD DSNAME=&&LOADSET, DISP=C(MOD,PASS), 
// UNIT=SYSSQ,SPACE=CTRK, (€30,10)) 
4/SYSIN DD % 

(source program) 

//LOAD EXEC PGM=LOADER, PARM="MAP,LET*,COND=(€5,LT, 
07 COBOL) 

SA/SYSLIN DD DSNAME=% .COBOL .SYSLIN, DISP=COLD, 
// DELETE) 
S/SYSLOUT DD SYSOUT=A 
S/SYSLIB DD DSNAME=SYS1.COBLIB, DISP=SHR 
7/7 SYVSOUT DD SYSOUT=A 
//TAXRATE DD enue TAXRATE, DISP=OLD 


“/SYSIN | DD 


(Data for Loaded Program) 
7% 


Figure 44. Input Deck for a Compile-Load Job 


Figure 45 on page 137 shows the compilation and loading of 
three modules. In the first three steps, the OV/VS FORTRAN 
CFORTVS) compiler is used to compile a main program, MAIN, and 
two subprograms, SUB1 and SUB2. Each of the object modules is 
placed in a sequential data set by the compiler and passed to 
the loader job step. In addition to the FORTRAN library, a 
private library, MYLIB, is used to resolve external references. 
In the loader job step, MYLIB is concatenated with the SYSLIB 
DD statement. SUB1l and SUB2 are included in the program to be 
loaded by concatenating them with the SYSLIN DD statement. The 
SYSTERM statement is used to define the diagnostic output data 
set. The loaded program requires the FTOLFO01 and FTIOFOOL DD 
statements for execution, and it does not require data in the 
input stream. 
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77 ISOBX 
//STEPI 


//SYSLIN 
“/SYSIN 


JOB 
EXEC PGM=FORTVS, PARM=*NAME=MAIN, LOAD* 


DD DSNAME=&&GOFILE, DISP=(,PASS),UNIT=SYSSQ 
xX 


CSource module for MAIN) 


7% 
//STEP2 


S/SYSCLIN 
“/7SYSIN 


EXEC PGM=FORTVS, PARM="NAME=SUB1,LOAD' 


DD DSNAME=&&SUBPROG1, DISP=(, PASS), UNIT=SYSSQ 
x 


CSource module for SUB1) 


SK 
S/ STEPS 


S/SYSLIN 
S/SYSIN 


EXEC PGM=FORTVS, PARM="*NAME=SUB2,LOAD'* 


DD DSNAME=&&SUBPROG2, DISP=(,PASS),UNIT=SYSSQ 
x 


CSource module for SUB2) 


/* 
S/7STEPG 
//7SYSTERM 
SOSNSLIB 
1 
S/SYSLIN 
17 

7 


EXEC PGM=LOADER 

SYSOUT=A 
DD DSNAME=SYS1.FORTLIB,DISP=OLD 
DD DSNAME=MYLIB, DISP=OLD 
DD DSNAME=%.STEP1.SYSLIN, DISP=OLD 
DD DSNAME=%.STEP2.SYSLIN, DISP=OLD 
DSNAME=% .STEPS.SYSLIN, DISP=OLD 


o 
o 


DD 
//FTO1F001 DD DSNAME=PARAMS, DISP=OLD 


//FT10F001 DD SYSOUT=A 


7K 


Figure 45. 


Input Deck for Compilation and Loading of the Three 
Modules | 
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The loader can be referred to by either its program name, 
HEWLDRGO, or its alias, LOADER. The loader can be invoked 
through the EXEC statement, as described in "Input for the 
Loader™ on page 128, or through one of the following macro 
instructions. 


Sema) 


7 


pom 





specifies the symbolic name of the loader. The entry point 
at which execution is to begin is determined by the control 
program from the library directory entry. 


PARAM=(optionlistl, 


1) 
specifies, as a sublist, address parameters to be passed to 
the loader. The first fullword in the address parameter 
list contains the address of the option list for the loader 
and/or loaded program. The second fullword contains the 
address of the ddname list. If standard ddnames are to be 


ddname list may be omitted. 


specifies the address of a variable-length list 
containing the loader and loaded program options. 
This address must be written even though no real list 
is provided; for example, when the optionlist points 
to a halfword of zero. 


The option list must begin on a halfword boundary. 

The two high-order bytes contain a count of the number 
of bytes in the remainder of the list. If no options 
are specified, the count must be zero. 


The option list is free form, with the loader and 
loaded program options separated by a slash (/), and 
with each option separated by a comma. No blanks or 
zeros should appear in the list. 


specifies the address of a variable-length list 
containing alternative ddnames for the data sets used 
during loader processing. If the standard ddnames are 
used, this operand may be omitted. 
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f 
NM Z 











The format of the ddname list is identical to the 
format of the ddname list for invoking the linkage 
editor; the 8-byte entries in the list are as follows: 


[entry [ Alternate Nano For! 
ae cc 
[2 | net apelicabie 
[3 net apelicabte 
es ct 
rae 
7 
ra 
re 















specifies that the sign bit is to be set to 1 in the last 
fullword of the address parameter list. 


Figure 46 shows an Assembler language program that uses the LINK 
macro instruction to refer to the loader. 


SAVE €14,12) Initialize save 
: registers and point 
to new save area 


LA 13, SAVEAREA 

LINK EP=LOADER, PARAM=(PARM),VL=1 

L 13,4¢€13) 

RETURN €14,12),T 

DS OH 
PARM DC AL2CLENGTH) Length of options 
OPTIONS DC C*NOPRINT,CALL/X,Y,2Z'* loader and loaded 
LENGTH EQU ¥-OPTIGNS program options 
SAVEAREA DS 138F Save area 

END 
Figure 46. Using the LINK Macro Instruction to Refer to the 

Loader 


If desired, the loader may be used to process a program but not 
execute it. To invoke just the portion of the loader that 
processes input data, specify either the name HEWLOAD or the 
name HEWLOADR with a LOAD and CALL macro instruction. 


HEWLOAD loads and identifies the program. HEWLOAD returns the 
address of an 8-character name in register 1. This name can be 
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used with an ATTACH, LINK, LOAD, or XCTL macro instruction to 
invoke the loaded program. A user program that is going to 
attach a loaded program should avoid specifying SZERO=NO in its 
ATTACH macro. If SZERO=NO must be specified, the user program 
should issue a LOAD for the loaded program before performing the 


ATTACH and a DELETE for the loaded program after the ATTACH 


HEWLOADR loads the program but will not identify it. 
the entry point of the loaded program in register 0. 
Register 1 points to two fullwords: the first points to the 
begining of storage occupied by the loaded program; 
contains the size of the loaded program. 
be used in a FREEMAIN macro instruction to free 
storage occupied by the loaded program when it is no longer 


returns 


can then. 


needed. 


Figure 47 on page 141 shows an Assembler language program that 
uses the LOAD and CALL macro instructions to refer to HEWLOADR. 
Figure 48 on page 142 shows an Assembler language program that 
uses the LOAD and CALL macro instructions to refer to HEWLOAD. 
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HEWLOADR 


the second 
This location and size 
the 














r~ SAVE (146,12),T Initialize save registers 
: ‘ and point to new save area 








ST 13,SAVEAREA+4 
LA 13,SAVEAREA 
LOAD EP=HEWNLOADR Load the loader 
LR 15,0 Get its entry point address 
CALL C15), CPARML),VL=1 Invoke the loader 
LR 7,15 Save return code 
LR 5,0 Save entry to loaded program 
LR 6,1 Save pointer to list containing 
¥ Start address and length 
DELETE EP=HEWLOADR Delete loader 
CH 7,=H'G! Verify successful loading 
BH FREE Negative branch 
LR 15,5 Loading successful—get entry 
* point address for CALL 
CALL €15), CPARM2),VL=1 Invoke program 
FREE L 0,4(€6) Get length into register 0 
L 1,0¢6) Get start address 
FREEMAIN R,LV=(€0),A=C1) Delete loaded program 
| L 13,4¢€13) 
RETURN €14,12),T 
| DS OH 
PARMI1 DC AL2CLENGTHIL) Length of loader options 
OPTIONSI DC C*NOPRINT,CALL * Loader options 
LENGTH] ay ad 
PARM2 DC ALZCLENGTH2) Length of loaded program options 
OPTIONS2 DC C'x,Y,Z' Loaded program options 
LENGTH2 EQU ¥-OPTIONS2 
SAVEAREA DS 18F Save area 
END 


Figure 47. Using the LOAD and CALL Macro Instructions to Refer to HEWLOADR CLoading 
Without Identification) 
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SAVE (14,12),T Initialize save registers and 
: point to new save area 
ST 13,SAVEAREA+4 
LA 13,SAVEAREA 
LOAD EP=HEWLOAD Load the loader 
LR 15,0 Get its entry point address 
CALL (15), CPARM1),VL=1l Invoke the loader 
LR 7,15 Save the return code 
MVC PGMNAMC8),0C1) Save program name 
DELETE EP=HEWLOAD Delete the loader 
CH 7,=H"G! Verify successful loading 
H ERROR Negative branc 
LINK EPLOC=PGMNAM, PARM=CPARM2),VL=1 
; Loading successful, 
invoke program 
ERROR 13,4(13) 
RETURN €14,12),T 
DS OH 
PARM1 DC AL2CLENGTH1) Length of loader options 
OPTIONS] DC C*MAP * Loader options 
LENGTH] + ¥-OPTIONS1 
PARM2 DC AL2CLENGTH2) Length of loaded program options 
OPTIONS2 DC C'x,Y,Z' Loaded program options 
LENGTH2 EQU ¥-OPTIONS2 
SAVEAREA DS 18F Save area 
PGMNAM DS 2F Program name 
END 
Figure 48. Using the LOAD and CALL Macro Instructions to Refer to HEWLOAD CLoading 


With Identification) 


For further information on the use of these macro instructions, 
see ; 
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Loader output consists of a collection of diagnostics and error 
messages, and of an optional storage map of the loaded program. 
This output is produced in the data set defined by the SYSLOUT 

DD and SYSTERM DD statements. If these are omitted, no loader 

output is produced. 


SYSLOUT output includes a loader heading, and the list of 
options and defaults requested through the PARM field of the 
EXEC statement. The SIZE stated is the size obtained, and not 
necessarily the size requested in the PARM field. Error 
messages are written when the errors are detected. After 
processing 1s complete, an explanation of the error is written. 
Loader error messages are similar to those of the linkage editor 
and are listed in : 


SYSTERM output includes only numbered warning and error 
messages. These messages are written when the errors are 
detected. After processing is complete, an explanation of each 
error is written. 


The storage map includes the name and absolute address of each 
control section and entry point defined in the loaded program. 
Each map entry marked with an asterisk (€*) comes from the data 
set specified on the SYSLIB DD statement. Two asterisks (x) 
indicate the entry was found in the link pack area; three 
asterisks (X%¥*) indicate the entry comes from text that was 
preloaded by a compiler. The TYPE column indicates what each 
entry on the map is used for: SD=control section, LR=label 
reference, and PR=pseudoregister. 


The map is written as the input to the loader is processed, so 
all map entries appear in the same sequence in which the input 
ESD items are defined. The total size and storage extent of the 
loaded program are also included. For PL/I programs, a list is 
written showing pseudoregisters with their addresses assigned 
relative to zero. Figure 49 on page 1494 shows an example of a 
module map. The loader issues an informational message when the 
loaded program terminates abnormally. 
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OPTIONS 


NAME 


SAMPL2B 
SYSIN 
IHEDIA 
IHEVPA 
IHEVPCA 
THEDNC 
IHEDMA 
THEVFAA 
IHEIOB 
IHESARC 
IHEBEGA 
IHEERRA 
IHEITAZ 
IHEDCNB 
IHEVTB 


IHEQINV 
SYSIN 

IHEQLW3 
IHEQFVD 
IHEQEVT 
IHEQSFC 


IEW1001 
IEw1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 


IEW1001° 


IEwi00o1 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
IEW1001 
TEW1001 


TOTAL 
ENTRY 


IEW1001 


USED- PRINT ,MAP,NOLET, CALL, NORES, SIZE=424176 


, TYPE 


SD 
-SD 
sD 
SD 
LR 
SD 
SD 
LR 
SD 
LR 
LR 
LR 
LR 
LR 
SD 


* £ &# #@* # &# #8 &# & HB He EH 


PR 
PR 
PR 
PR 
PR 
PR 


IHEUPBA 
IHEUPAA 
IHETERA 
ITHEM9 1C 
IHEM9 1B 
IHEM91A 
IHEDDOD 
ITHEVPFA 
IHEVPDA 
THEDBNA 
IHEVSFA 
IHEVSBA 
IHEVCAA 
IHEVSAA 
IHEDNBA 
IHEUPBB 
IHEUPAB 
IHEVSEB 


LENGTH 
ADDRESS 


WARNING 


Figure 49. 





ADDR 


161E0 
17D48 
183Cc0 
18870 
189F8 
18CB8 
19010 
19160 
19488 
1A9CB 
1AE28 
1AE86 
1B81E 
1B862 
1BCFO 


00 
14 
28 
3€ 
58 
70 


5068 
17D00 


NAME 


SAMPL2BA 
LHEVQC 
IHEDIAA 
IHEVPAA 
IHEVFE 
IHEDNCA 
LHEDMAA 
IHEVPB 
IHEIOBA 
IHESADD 
IHEERR 
IHEERRE 
IHEITAX 
ILHELOD 
LHEVTBA 


LHEGERR 
IHEQLSA 
IHEQLW4 
IHEQCFL 
ILHEQSLA 


* *# &© &@ # # &# &# H& 8 HH HF He 


TYPE ADDR 

SD 16EC8 
SD 17D80 
LR 183C0 
LR 18870 
SD 18BE8 
LR 18CB8 
LR 19010 
SD 19248 
LR 19488 
LR 1A9DE 
SD TAE68 
LR TB4E2 
LR 1B82A 
SD 1BA5O 
LR 1BCFO 
PR 4 
PR 18 
PR 2¢ 
PR 40 
PR 60 


NAME 


IHEMAIN 
IHEVQCA 
IHEDIAB 
IHEVFC 
IHEVFEA 
IHEDOA 
IHEVFD 
IHEVPBA 
IHEIOBB 
IHESAFF 
IHEERRD 
IHEIOF 
IHEITAA 
IHELODG 
IHEVQA 


SAMPL2BB 
ILHEQLWO 
IHEQLWE 
IHEQFOP 
IHEQSAR 


** &©£ © © # & &# # 8 He He HF 


TYPE 


SD 
LR 
LR 
SD 
LR 
SD 
SD 
LR 
LR 
LR 
LR 
SD 
LR 
LR 
SD 


-PR 


PR 
PR 
PR 
PR 


ADDR 


17CF8 
17D80 
183C2 
189D0 
18BE8 
18F30 
19108 
19248 
19490 
1AA18 
1AE68 
1B580 
1B83E 
1BA50 
1BD78 


1c 
30 
48 
64 


~- UNRESOLVED EXTERNAL REFERENCE (NOCALL SPECIFIED) 


Module Map Format Example 


NAME 


IHENTRY 
IHEVQB 
IHEVPE 
LHEVFCA 
LHEVSC 
IHEDOAA 
LHEVFDA 
IHEXIS 
IHEIOBC 
IHEPRT 
IHEERRC 
IHEIOFB 
IHEDCN 


-IHEIODP 


IHEVQAA 


SAMPL2BC 
IHEQLW1 
IHEQLCA 
IHEQADC 
IHEQLWF 


* * &© # © &#© © & &# & +e &F He 


TYPE 
SD 


SD 


SD 
LR 
SD 
LR 
LR 
SD 
LR 
SD 
LR 
LR 
SD 
LR 
LR 


PR 
PR 
PR 
PR 
PR 
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ADDR 


17D00 
17FD8 
18608 
189D0 
18C08 
18F30 
19108 
193F0 
19498 
1AB70 
1AE72 
1B580 
1B860 
1BAS2 
1BD78 


20 
34 
4C 
68 


NAME 


IHESPRT 
IHEVQBA* 
IHEVPEA* 
IHEVPC * 
IHEVSCA* 
IHEDOAB* 
IHEVFA * 


-IHEXISO* 


IHEIOBD* 
IHEPRTA* 
IHEERRB* 
IHEIOFA* 
IHEDCNA* 
IHEIODT* 


IHEQSPR 
IHEQLW2 
LHEQVDA 
IHEQXLV 
IHEORTC 


TYPE 


SD 
LT 
LR 
SD 
LR 
LR 
SD 
LR 
LR 
LR 
LR 
LR 
LR 
LR 


PR 
PR 
PR 
PR 
PR 


ADDR 


17D10 
17FD8 
18608 
169F8 
18C08 
18F32 
19160 
193F0 
194A0 
1AB70 
VAE7C 
1B582 
1B860 
1BB4A 


10 
24 
38 
50 
6C 

















wre 
a 
Mee 








This appendix contains sample linkage editor programs. The 
material presented for each program includes a description of 
the program, the job control language necessary for the linkage 
editor job step, linkage editor control statements (Cif any), and 
the linkage editor output. The sample programs are: 


e Link-editing a COBOL and a FORTRAN object module CCOBFORT) 


€ Replacing one control section with another by using the 
REPLACE statement CRPLACJOB) 


° Creating a multiple-region overlay program CREGNOVLY) 


e Placing the control statements for the multiple region 
yea Rl in a partitioned data set, and using them 


The output for each program includes a cross-reference table, a 
module map, a control statement listing, and diagnostic 
messages, if any. 


SAMPLE PROGRAM COBFORT 


Job Control Language 


Sample program COBFORT link-edits a COBOL object module and a 
FORTRAN object module to form one load module. The source 
programs were compiled in two steps previous to the linkage 
editor job step, and the output from each compilation was placed 
in data set &&OBJMOD. 


The job control language for the linkage editor job step of this 
sample program is: 


//LKED PGM=HEWL , PARM='XREF* 

S/SYSUTI DSNAME=&&UT1,UNIT=SYSDA, SPACE=CTRK, 
11 €100,10)) 

S/SVSLIB DSNAME=SY5S1.COBLIB, DISP=SHR 

// DSNAME=SYS1.FORTLIB, DISP=SHR 


D 
7/SYSLMOD DSNAME=&&LOADMD(GO), UNIT=SYSDA, 
1/ DISP=C(NEW, PASS), SPACE=CTRK, 
4/ €100,10,1)) 
4/7SYSPRINT SYSOUT=A 
“/7SVYSLIN DSNAME=&&0BJMOD, DISP=COLD, DELETE) 
7% 





Statement Explanation 


EXEC Causes the execution of the linkage editor. The 
PARM field option requests a cross-reference table 
and a module map to be produced on the diagnostic 
output data set. 


SYSUT1 Defines a temporary direct access data set to be 
used as the intermediate data set. 
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SYSLIB Defines the automatic call library; the call 
. libraries for COBOL and FORTRAN are concatenated; os 
both are used to resolve external references. co * 


SYSLMOD Defines a temporary data set to be used as the 
output module library; the load module is assigned a 
member name of GO, and is passed to a subsequent 
step for execution. 


SYSPRINT Defines the diagnostic output data set, which is 
assigned to output class A. 


SYSLIN Defines the primary input data set, &&OBJMOD, which 
| contains both input object modules; this data set 
was passed from a previous job step and is to be 
deleted at the end of this job step. 


Linkage Editor Output 


Figure 50 on page 147 shows the linkage editor output for 
COBFORT. The listing header indicates the options specified 
CXREF), and the SIZE option values in decimal (196608 for valuel 
and 65536 for value2). Because XREF is specified, the heading 
CROSS REFERENCE TABLE precedes the rest of the output. 


Figure 50 also shows the module map for COBFORT. IPCT30 and 
TX652F are the names of the input control sections. The rest of 
the control sections are either from the COBOL automatic call 
library or from the FORTRAN automatic call library. (They can 
be distinguished by the initial three letters; ILB indicates a 
COBOL control section, IHC a FORTRAN control section.) The 
origin and length (in hexadecimal) of each control section 
follow the name. 


To the right of each control section is a list of the entry 
names defined in each control section. The location Cin 


hexadecimal) of each entry name is also given. For example, in Se” 


control section IHCCOMH2 Cthe asterisk is not a part of the 
name; it indicates that the control section is from the 
automatic call library), entry name SEQDASD is defined at 
location 154A. 


Figure 50 shows the cross-reference table for COBFORT. The 
table contains the location of any address constant that refers 
to a symbol defined in another control section. The symbol the 
address constant refers to is also listed, along with the 
control section in which the symbol is defined. For example, at 
location 1FO in control section IPCT30 (determined by using the 
module map; 1F0 falls between origin 00 and origin 360), an 
address constant refers to symbol IHDFDISP, defined in control 
section IHDFDISP. 


The entry address is 00 and the total length of the load module 
is GAE8. Note that the length of the module is rounded up to a 
doubleword boundary. 


The disposition message at the end of the output in Figure 50 

indicates that the load module GO has been added to the output 
module library. The library did not contain any other module 

with that name. The four asterisks identify the message. 


SAMPLE PROGRAM RPLACJOB 


Sample program RPLACJOB shows the use of the REPLACE statement 

to replace one control section with another. The source program 
for the new control section (NEWMOD) is processed in a previous 
job step and passed to the linkage editor job step. The control 
section CSUBONE) to be replaced is in an existing load module. a 
Figure 51 on page 148 shows the linkage editor output for the (t 

job step that created this load module. Note that the entry R 
address is F0, which is the location of the entry point MAINMOD 


ere 


(specified on the ENTRY control statement). 


146 MVS/XA Linkage Editor and Loader User's Guide 














Module Map 





F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF 
DEFAULT OPTIONS(S) USED - SIZE=(196608,65536) 


CROSS REFERENCE TABLE 








CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
IPCT30 00 360 
TX652F 360 1E0O 
IHCFCOMH* 540 CD9 
IBCOM# 540 FDIOCS# SFC INTSWTCH 11IFE 
IHCCOMH2* 1220 434 
SEQDASD 154A 
IHDFDISP* 1658 626 
IHCFCVTH* 1c80 119D 
ADCON# 1c80 FCVAOUTP 1ID2A FCVLOUTP 1DBA FCVZOUTP 1FOA 
FCVIOUTP 22B8 FCVEOUTP 27BA FCVCOUTP 29D4 INT6SWCH 2CBB 
IHCFINTH® 2E20 39E 
ARITH# 2E20 ADJSWTCH 30D8 
IHCFIOSH* 31c0 100E 
FIOCS# 31c0 
IHCUOPT * 41D0 8 
IHCTRCH #* 41D8 2D4 
IHCERRM 41D8 
IHCUATBL*® 44B0 638 
Cross-Reference Table 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
FO IHDFDISP IHDFDISP 1F4 TX652F TX652F 
410 . IBCOM# IHCFCOMH 5FC SEQDASD IHCCOMH2 
1108 ADCON# IHCFCVTH 1100 FIOCS# IHCFIOSH 
110c ARITH# IHCFINTH 112C ADJ SWTCH IHCFINTH 
1128 IHCUOPT IHCUOPT 1110 FCVEOUTP IHCFCVTH 
1114 FCVLOUTP IHCFCVTH 1118 FCVIOUTP IHCFCVTH 
111¢C FCVCOUTP JTHCFCVTH 1120 FCVAOUTP LHCFCVTH 
1124 FCVZOUTP IHCFCVTH 10E0 IHCCOMH2 IHCCOMH2 
10E4 IHCERRM IHCTRCH 14a9 IHCFCOMH IHCFCOMH 
14AC IHCFCOMH IHCFCOMH 1268 IHCERRM IHCTRCH 
1264 IBCOM# ITHCFCOMH 2C7C IBCOM# IHCFCOMH 
2C78 IHCERRM ITHCTRCH 311¢C IBCOM# IHCFCOMH 
3120 INTSWTCH IHCFCOMH 30D4 INT6SWCH IHCFCVTH 
30D0 IHCUOPT ILHCUOPT 3128 ADCON# IHCFCVTH 
3124 FIOCS# IHCFIOSH 32F8 IHCERRM IHCTRCH 
3FF8 IHCUATBL ITHCUATBL 4004 IBCOM# IHC FCOMH 
43D0 IBCOM# ITHCFCOMH 43D4 ADCON# IHCFCVTH 
43D8 FIOCS# IHCFIOSH 
ENTRY ADDRESS 00 
TOTAL LENGTH 4AE8 


£EEGO 


DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 


AUTHORIZATION CODE IS 


Figure 50. 


0. 


Linkage Editor Output for Sample Program COBFORT 
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F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF,LIST ri « 


DEFAULT OPTION(S) USED - SIZE=(196608, 65536) ( : 
IEWOO00 ENTRY MAINMOD a 


CROSS REFERENCE TABLE 


CONTROL SECTION _ ENTRY 


NAME ORIGIN LENGTH NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
SUBONE 00 EF 
SUB1 00 
MAINMOD FO 146 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
T1C SUBONE SUBONE 
ENTRY ADDRESS FO 
TOTAL LENGTH 238 
****GO DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 
AUTHORIZATION CODE IS 0 


Figure 51. Linkage Editor Output for Job Step that Created SUBONE 


Job Control Language 


The job control language for the replacement job step of this 
sample program is shown below. 


//LKED PGM=HEWL ,PARM='XREF,LIST! 

//S8YSUT1 UNIT=SYSDA, SPACE=(TRK, (100,10)) 
//TNPUTX DSNAME=LOADLIB, DISP=OLD, UNIT=SYSDA, 

11 VOL=SER=SCRTCH os 
//SYSLMOD DSNAME=LOADLIB(GO), DISP=OLD,UNIT=SYSDA, —_ 
Vf VOL=SER=SCRTCH | ae 
//SYSPRINT SYSOUT=A 


//SYSLIN DSNAME=&&OBJMOD, DISP=COLD, DELETE), 
// UNIT=SYSDA 
47 DD X 


Linkage Editor Control Statements 
7% 





Ne 
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Statement Explanation 


EXEC Causes the execution of the linkage editor. The PARM 
field options request a cross-reference table and a 
module map (CXREF), and a control statement listing 
(LIST) to be produced on the diagnostic output data 





set. 

SYSUT1 Defines a temporary direct access data set to be 
used as the intermediate data set. 

INPUTX Defines a permanent data set, used later as 
additional linkage editor input. 

SYSLMOD Defines a permanent data set to be used as the 


output module library. Note that it is the same data 
set that was described on the INPUTX DD statement. 
The output load module is added to the data set, 
under the member name GQ. 


SYSPRINT Defines the diagnostic output data set, which is 
assigned to output class A. 


SYSLIN Defines the primary input data set, &&OBJMOD, which 
contains the object module for the replacement 
control section. This data set is temporary and was 
passed from a previous job step; it is to be deleted 
at the end of this job. This statement also 
concatenates the input stream to the primary input 
data set. The input stream contains linkage editor 
control statements that must be followed by a /X 
statement. 


Figure 52. Job Control Statements for RPLACJOB 











LINKAGE EDITOR CONTROL STATEMENTS 


The input stream contains the linkage editor control statements 
that are necessary for the replacement of SUBONE with NEWMOD. 
The control statements are shown below: 


ENTRY MAINMOD 
REPLACE SUBONECNEWMOD) 
INCLUDE INPUTXCGO) 


Statement Explanation 
ENTRY Specifies that the entry point is to be MAINMOD. 


REPLACE Specifies that control section SUBONE in the module 
that follows the REPLACE statement is to be replaced 
by control section NEWMOD. 


INCLUDE Specifies additional input: member GO of the data 
set described on the INPUTX DD statement. This 
library member contains the control section to be 
replaced. Because this member name is identical to 
that specified on the SYSLMOD DD statement, the 
eu Eue load module replaces the existing library 
member. 


Figure 53. Linkage Editor Control Statements for RPLACJOB 
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Linkage Editor Output 


Figure 54 shows the linkage editor output for sample program 

RPLACJOB. The listing header indicates the options specified 
CXREF and LIST), and the oe option values used (196608 for 

valuel and 65536 for 


F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF,LIST 
DEFAULT OPTION(S) USED - SIZE=(196608,65536) 


IEWO000 ENTRY MAINMOD 
IEwoo0o REPLACE SUBONE ‘NEWMOD) 
IEwO090 INCLUDE INPUTX(GO) 
CROSS REFERENCE TABLE 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
NEWMOD 09 Fl 
MAINMOD FA 146 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION LOCATION REFERS TO SYMBOL IN CONTROL SECTION 
124 NEWMOD NEWMOD 
ENTRY ADDRESS F8 
TOTAL LENGTH 240 


oseeGn NQW REPLACED IN DATA SET 
AUTHORIZATION CODE IS 


Figure 54. Linkage Editor Output for Sample Program RPLACJOB 


Because the LIST option is specified, a control statement 

is produced. Each control statement is preceded by a 
special message number, IEW0000. Because XREF is specified, 
heading CROSS REFERENCE TABLE precedes the rest of the output. 


The module map shows that control section NEWMOD is now part of 


the load module, and that control section SUBONE has been 


deleted. The new entry address is F8, because NEWMOD is longer 
than SUBONE. The total length of the load module is 240 bytes. 


The cross-reference table indicates that at location 124 in 
MAINMOD, an address constant refers to symbol NEWMOD, defined in 
control section NEWMOD. Note that before the replacement 
occurred, the address constant in MAINMOD referred to SUBONE, 


defined in control section SUBONE (Figure 51 on page 148). When 


the REPLACE statement is used to replace a control section, 


references to the old control section from within the same input 


module are also changed. 
The disposition message indicates that the output load module 
(GO) has been added to the output module library. 
SAMPLE PROGRAM REGNOVLY 

Sample program REGNOVLY creates a multiple-region overlay 
structure. The structure produced is shown in Figure 55 on 
page 151. In this program, some of the references between 
control sections are: | 

CSA to CSE 

CSB to CSE 

CSB to CSD 


CSD to CSC 


The reference from CSB to CSE is a valid exclusive call, because 


there is a reference to CSE in the segment common to both CSB 


and CSE; the reference from CSD to CSC is invalid, because there 


is no reference to CSC in the common segment. 
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REGION 1 


CSA Root Segment 1 






CSE Segment 5 


| 


Segment 2 





CSC Segment 3 CSD Segment 4 


REGION 2 Gamma 
CSF Segment 6 CSG Segment 7 


i I 


Pigura 55. Overlay Tree for Multiple-Region Sample Program REGNOVLY 


The source programs for all the control sections were compiled 
in previous job steps. All the object modules were placed in 
oe same data set, which was passed to the linkage editor job 
step. 


Job Control Language 


The job control language for the linkage editor job step of this 
sample program is shown below. 
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/7/LKED 
4/SYSUTI1 
77 

| S“SYSLIB 
//SYSLMOD 
11 
7/7SYSPRINT 
/S/SYSLIN 
17 


Statement 
EXEC 


SYSUTI 


SYSLIB 


SYSLMOD 


SYSPRINT 


SYSLIN 


Figure 56. 
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EXEC PGM=HEWL, PARM="XREF,LIST,OVLY,LET' ( 
DD ETT VAL TF eeu aa ca dich ae : - 
DD DSNAME=SYS1 .COBLIB, DISP=SHR 

DD DSNAME=&&OVLYJB(GO),UNIT=SYSDA, 


DISP=CNEW, PASS), SPACE=CTRK, (€100,10,1)) 
DD SYSOUT=A 
DD DSNAME=&&0BJMOD, DISP=COLD, DELETE) 

x 


DD 
penkege Editor Control statements 
7 


Explanation 


Causes the execution of the linkage editor. The 
PARM field options request a cross-reference table 
and a module map (CXREF), and a control statement 
listing (LIST) to be produced on the diagnostic 
output data set. The module is to be assigned the 
overlay attribute COVLY), and marked executable in 
spite of severity 2 errors (LET). The LET option is 
specified to permit testing of the output module, 
even though an invalid exclusive call is present. 
The XCAL option allows only valid exclusive calls. 


Defines a temporary direct access data set to be 
used as the intermediate data set. 


Defines the automatic call library (SYS1.COBLIB) to | 

be used to resolve external references. All control ee 
sections from this library are placed in the root 

segment; they remain there unless they are 

repositioned. 


Defines a temporary data set to be used as the 
output module library; the load module is assigned 
the member name GO and is passed to a subsequent 
step for execution. 


Defines the diagnostic output data set, which is 
assigned to output class A 


Defines the primary input data set, &&OBJMOD, which 
contains the object modules for the overlay 
structure. This data set is temporary and was 
passed from a previous job step; it is to be deleted 
at the end of this job. This statement also 
concatenates the input stream to the primary input 
data set. The input stream contains linkage editor 
control statements, which must be delimited by a /X 
statement. 


Job Control Statements for REGNOVLY 


ae . 
\ tl pe 
ed 
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Linkage Editor Control Statements 


ff The input stream contains the linkage editor control statements 
| that structure the overlay program. The control statements are: 


INSERT CSA 
ENTRY CSA 
OVERLAY ALPHA 
INSERT CSB 
OVERLAY BETA 
INSERT CSC 
OVERLAY BETA 
INSERT CSD 
OVERLAY ALPHA 
INSERT CSE 
OVERLAY GAMMACREGION) 
INSERT CSF 
OVERLAY GAMMA 
INSERT CSG 


Linkage Editor Output 
Figure 57 on page 154 shows the linkage editor output for sample 


program REGNOVLY. The list header indicates the options 
specified and the SIZE option values used. 
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F64-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XREF,LIST,OVLY,LET 
DEFAULT OPTION(S) USED - SIZE=(196608, 65536) 


IEWO000 INSERT CSA 
IEWOO0O ENTRY CSA 
IEWOOO0O OVERLAY ALPHA 
IEWOOO0O INSERT CSB 
IEWOO00 OVERLAY BETA 
IEWOO000 INSERT CSC 
IEWOOOO OVERLAY BETA 
IEWOO000 INSERT CSD 
IEWOO0O OVERLAY ALPHA 
IEWOO0O INSERT CSE 
IEWOO00 OVERLAY GAMMA (REGION) 
IEWOO00O INSERT CSF 
IEWOOO00 OVERLAY GAMMA 
IEWO000 INSERT CSG 
IEWO172 2 CSE 
ITEWO182 4 CSC 


Root Segment 1: 


CROSS REFERENCE TABLE 


CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION 

$SEGTAB 00 34 1 

CSA 38 366 1 

ILBODSPO* 3A0 6F8 1 

ILBOSTPO* A98 35 1 

ILBOSTP 1 AAE 

$ENTAB ADO 30 1 


LOCATION REFERS TO SYMBOL 


LOCATION REFERS TO SYMBOL 


IN CONTROL SECTION SEG. NO. 


IN CONTROL SECTION SEG. NO. 


2co0 ILBODS PO ILBODSPO 1 2C4 

2c8 CSG 2cc 

2D0 CSB 2 2D4 

Segment 2: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION 

CSB BOO 360 2 
$ENTAB E60 18 2 


D54 ILBODSPO ILBODSPO 1 D50 
D58 CSE CSE D60 
D5c CSD CSD 4 
Segment 3: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION 
csc E78 336 3 : 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 


10cC ILBODSPO ILBODSPO 1 
10D0 ILBOSTP1 ILBOSTPO 1 
Segment 4: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION 
CSD E78 362 4 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
10CC ILBODSPO ILBODSPO 1 
10D4 ILBOSTP1 ILBOSTPO 1 


Figure 57 (Part 1 of 2). 


NAME LOCATION NAME 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION 


ILBOSTPO ILBOSTPO 

CSE CSE 

ILBOSTP1 ILBOSTPO 
NAME LOCATION NAME 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION 


ILBOSTPO ILBOSTPO 
ILBOSTP1 ILBOSTPO 
NAME LOCATION NAME 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION 


10C8 


NAME LOCATION 


ILBOSTPO ILBOSTPO 


NAME LOCATION NAME 


LOCATION REFERS TO SYMBOL IN CONTROL SECTION 


10C8 
10D0 





ILBOSTPO ILBOSTPO 
CSC csc 


LOCATION 


SEG. NO. 


LOCATION 


SEG. NO. 
1 
1 


LOCATION 


SEG. NO. 
1 


LOCATION 


SEG. NC. 


Linkage Editor Output for Sample Program REGNOVLY 
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CROSS REFERENCE TABLE 





Segment 5: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
CSE BOO 336 5 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
DS4 ILBODSPO ILBODSPO 1 DSO ILBOSTPO ILBOSTPO 1 
p58 ILBOSTP 1 ILBOSTPO 1 
Segment 6: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION NAME LOCATION © NAME LOCATION 
CSF 11£0 2FA 6 | 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
1430 ILBOSTPO ILBOSTPO 1 1434 ILBOSTP 1 ILBOSTPO 1 
Segment 7: 
CONTROL SECTION ENTRY 
NAME ORIGIN LENGTH SEG. NO. NAME LOCATION NAME LOCATION NAME LOCATION NAME LOCATION 
CSG 11E0 336 7 
LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 
1434 ILBODSPO ILBODSPO 1 1430 ILBOSTPO ILBOSTPO 1 
1438 ILBOSTP1 ILBOSTPO 
ENTRY ADDRESS 38 . 
TOTAL LENGTH 1518 
##%8G0O DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 
AUTHORIZATION CODE IS QO. 





DIAGNOSTIC MESSAGE DIRECTORY 
IEWO172 ERROR - EXCLUSIVE CALL FROM SEGMENT NUMBER PRINTED TO SYMBOL PRINTED. 
IEWO182 ERROR - INVALID EXCLUSIVE CALL FROM SEGMENT NUMBER PRINTED TO SYMBOL PRINTED. 


( Figure 57 (Part 2 of 2). Linkage Editor Output for Sample Program REGNOVLY 





Because the LIST option was specified, the contro] statement 
listing 1s produced. Each control statement is preceded by a 
special message number, IEWO000. 


The control statement listing is followed by two diagnostic 
message numbers CIEW0172 and IEW0182). The explanation of the 
messages and the information following each message are given at 
the end of the output in the diagnostic message directory. 


The output for each segment contains a module map and a 
cross-reference table. The segments are listed as they appear 
in the overlay structure, top to bottom, left to right, and 
region by region. (Note that this is also the sequence in which 
the OVERLAY and INSERT statements must be given.) 


Within each segment, a module map lists the control sections in 
ascending sequence according to their assigned origin. The 
origin, length, and segment number are listed for each control 

- section, along with any entry names and the location at which 
each entry name is defined. For example, the root segment has 
five control sections: $SEGTAB, which is always the first 
control section in the root segment; CSA, which is from the 
object module input; ILBODSPO and ILBOSTPO0, which are from the 
automatic call library Cindicated by an asterisk) and were not 
repositioned; and $ENTAB, which, when present, is always the 
last control section in any segment (Cas also in segment 2). One 
entry name is defined, ILBOSTP1 at location D58 ain control 
section ILBOSTPO. 


address constants that refer to symbols defined in other control 
sections. The location of the address constant is followed by 
the symbol referred to, the control section in which the symbol 
is defined, and the segment in which the control section is 


C The cross-reference table for each segment contains all the 
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located. For example, in the root segment, an address constant 


at location 11E0 refers to symbol CSG, which is defined in a 
control section CSG in segment 7. Although the region is not ae 
given, the overlay tree in Figure 55 on page 151 shows that ee 


segment 7 is in region 2. 


At the end of the output for all the segments are the entry 
address and total length. The entry address is 38, which is the 
origin of CSA, the specified entry point. The total length 
given refers to main storage used, not device storage. The 
length given, therefore, is that of the longest path. The 
longest path is that formed by the root segment and segments 2, 
4, and 7; the length given is 1518. 


However, if the given lengths of the control sections in each 
segment are added, the result is 14D3. The discrepancy exists 
because the given lengths do not include the padding bytes 
necessary to make control sections begin on a doubleword address 
(multiple of 8). For example, in the root segment, the length 
of $SEGTAB is 34; however, the origin of CSA which follows 
S$SEGTAB is 38 Cdecimal 56). Four additional bytes are needed so 
that the origin of CSA is a multiple of 8. 


The disposition message indicates that the load module GO has 
been added to the output module library. The library did not 
contain any other module by that name. The four asterisks 
identify the message. 


The last item in the output for this sample program is the 
diagnostic message directory. The directory contains the text 
for the message numbers listed after the control statement 
listing. The directory must be correlated to the information 
following the number to interpret the message. 


For example, message IEW0172 is an error message that indicates 

that an exclusive call was made from the segment number printed 

(2) following the message number to the symbol printed (CSE). ’ 
The output for segment 2 indicates that this call is at location Mister 
D58 in control section CSB, and the symbol is defined in control 

section CSE in segment 5. This is the valid exclusive call from 

CSB to CSE described earlier. CIf XCAL were specified, a 

warning message would be issued instead of an error message. ) 


If an invalid exclusive call is detected, message IEW0182 
appears as shown. This is also an error message; it indicates 
that an invalid exclusive call was made from segment 4 to symbol 
CSC. This call is at location E78 in control section CSD, and 
the symbol is defined in control section CSC in segment 3. This 
is ve invalid exclusive call from CSD to CSC, also described 
earlier. 


SAMPLE PROGRAM PARTDS 


Sample program PARTDS illustrates that linkage editor control 

statements can be placed in a separate data set and then used as 
input. For convenience, the control statements are those for 
sample program REGNOVLY, described previously. These control 
statements are placed in a partitioned data set. When the 
member that contains the control statements is referenced, the 
linkage editor uses the control statements to produce the 
overlay structure shown in Figure 55 on page 151 


Figure 58 on page 157 shows the input statements for the 
IEBUPDTE utility program used to place the control statements in 
a partitioned data set. 
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C //PARTDS JOB (accounting information) 


//CTLG EXEC PGM=IEBUPDTE, PARM=( NEW ) 
//SYSUT2 DD DSNAME=OVLYLIB, UNIT=2314,VOL=SER=DA028,DISP=(NEW,KEEP), 
Pe SPACE=(TRK,(10,5,2)),DCB=( LRECL=80, BLKSIZE=80, RECFM=F ) 
//SYSPRINT DID SYSOUT=A 
//SYSIN DD * 
if ADD NAME=OVLY , LEVEL=00 , SOURCE=00, LIST=ALL 
NUMBER NEW1=10, INCR=5 
INSERT CSA 


ENTRY CSA 

OVERLAY ALPHA 

INSERT CSB 

OVERLAY BETA 

INSERT CSC 

OVERLAY BETA 

INSERT CSD 

OVERLAY ALPHA 

INSERT CSE 

OVERLAY GAMMA( REGION ) 
INSERT CSF 

OVERLAY GAMMA 

INSERT CSG 
7 ENDUP | 

ee | 


Figure 58. Input Statements for IEBUPDTE Utility Program 








in previous job steps. All the object modules were placed in 
the same data set, which was passed to the linkage editor job 
aye input modules are those used for sample program 


( The source programs for all the control sections were compiled 


Job Control Language 


The job control language for the overlay program job step of 
this sample program is shown below. 


//LKED PGM=HEWL,PARM="XREF,LIST,OVLY,LET'* 
//SYSUTI1 DD DSNAME=&&UT1, UNIT=SYSDA,SPACE=CTRK, 
// €100,10)) 

//OVLYCDS DD DSNAME=OVLYLIB, UNIT=SYSDA, 

17 VOL=SER=SCRTCH, DISP=OLD 

//SYSLIB DD DSNAME=SYS1.COBLIB, DISP=SHR 
//SYSLMOD DD DSNAME=&&0VLYJBC(GO),UNIT=SYSDA, 


// DISP=CNEW, PASS), SPACE=C(TRK, €100,10,1)) 
4/SYSPRINT DD SYSOUT=A 


S/SYSLIN a DSNAME=&&OBJMOD, DISP=COLD, DELETE) 
47 % 


CLankage Editor Control Statements) 
7% 
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Statement 
EXEC 


SYSUT1 


OVLYCDS 


SYSLIB 


SYSLMOD 


SYSPRINT 


SYSLIN 


Figure 59. 


Explanation | 

Causes the execution of the linkage editor. The PARM 
field options request a cross-reference table and a 
module map CXREF), and a control statement listing 
(LIST) to be produced on the diagnostic output data 
set. The output load module is to be assigned the 
overlay attribute COVLY), and is to be marked | 
executable despite severity 2 errors (LET). 


Defines a temporary direct access data set to be 
used as the intermediate data set. 


Defines a permanent data set to be used later as 
additional input; this is the partitioned data set 
which was created by I[EBUPDTE and contains the 
control statements for structuring the overlay 
program. 


Defines the automatic call library CSYS1.COBLIB) to 
be used to resolve external references. All control 
sections from this library are placed in the root 
segment; they remain there unless they are 
repositioned. 


Defines a temporary data set to be used as the 
output module library; the load module is to be 
assigned the member name GO, and is passed to a 
subsequent step for execution. 


Defines the diagnostic output data set, which is 
assigned to output class A 


Defines the primary input data set, &&0BJMOD, which 
contains the object modules for the overlay 
structure. This data set is temporary and was 
passed from a previous job step; it is to be deleted 
at the end of this job. This statement also 
concatenates the input stream to the primary input 
data set. The input stream contains linkage editor 
control statements that must be delimited by a /X 
statement. 


Job Control Statements for PARTDS 


Linkage Editor Control Statements 


The input stream contains an INCLUDE statement, as follows: 


INCLUDE OVLYCDSCOVLY) 


This statement causes the control statements to be read from the 
partitioned data set described on the OVLYCDS DD statement. The 
member name of the statements is OVLY, the same name used in the 
ADD statement for the utility program. 
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Linkage Editor Output 


The output of this sample program is identical to the output 
from the REGNOVLY sample program, with one exception. The list 
of control statements begins with the statement 


IEW0000 INCLUDE OVLYCDSCOVLY) 


This statement is followed by a list of the control statements 
read from the additional input data set specified in this 
INCLUDE statement. The rest of the output is identical to that 
shown in Figure 57 on page 154. 
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This appendix describes the record-processing capacities of the 
linkage editor, the types of devices that can be used for the 
intermediate data set (SYSUT1), and the amount of virtual 
storage the linkage editor requires. 


Capacities 


The minimum storage requirement and processing capacities of the 

| linkage editor program are described in Figure 60. To increase 
the capacity for processing external symbol dictionary records, 
intermediate text records, relocation dictionary records, and 
identification records, you should increase value] and/or 
‘decrease’ value2 of the SIZE option, but in no case may the 
record length ever exceed the track length for the device or 

| 32760 bytes, whichever is lower. The number of overlay segments 

and regions that can be processed is not affected by increasing 


the storage available. 
Capacity 
(Bytes } 


Virtual storage allocated Cin bytes) 


Maximum number of entries in composite external 
symbol dictionary CCESD) 


Maximum number of intermediate text records 


Maximum number of relocation dictionary (CRLD) 
records 


a — sf 
Maximum number of segments per program 255 


Maximum number of overlay regions per program 
Maximum blocking factor for input object modules 
object modules (number of 80-column card images 
per physical record) 
Maximum blocking factor for SYSPRINT output 
(number of 1l2l-character logical scecords per 
physical record) 
Output text record length Cin bytes): 

On IBM 2305-2 Fixed Head Storage 

On IBM 3330 Disk Storage 

On IBM 3330-11 Disk Storage 


On IBM 3340 Direct Access Storage 


On IBM 3544 Direct Access Storage 
On IBM 3350 Direct Access Storage 
On IBM 3375 Direct Access Storage 
On IBM 3380 Direct Access Storage 








Figure 60. Linkage Editor Capacities for Minimal SIZE Values 
(96K bytes, 6K bytes) 
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Note to Figure 60: 


1 The maximum output text record length is achieved when yalue2 
of the SIZE parameter is at least twice the record length 
size. For example, on a 3330, 12288 byte records are written 
when yvalue2 is at least 24576. 


For the composite external symbol dictionary, the number of 
entries permitted can be computed by subtracting, from the 
maximum number given in Figure 60 on page 160, one entry for 
each of the following: 


e A data definition name (ddname) specified in LIBRARY 
statements 


e A data definition name (ddname) specified in INCLUDE 
statements 


e An ALIAS statement 


e A symbol in REPLACE or CHANGE statements that are in the 
largest group of such statements preceding a single object 
module in the input to the linkage editor 


° The segment table CSEGTAB) in an overlay program 
° An entry table CENTAB) in an overlay program 


To compute the number of intermediate text records that will be 
produced during processing of either program, add one record for 
each group of x bytes within each control section, where x is 
the record size for the intermediate data set. The minimum 
value for x is 1024; a maximum is chosen depending on the amount 
of storage available to the linkage editor and the devices 
allocated for the intermediate and output data sets. 


The number of intermediate text records that can be handled by a 
linkage editor program is less than the maximums given in 

Figure 60 on page 160 if the text of one or more control 
sections is not in sequence by address in the input to the 
linkage editor. 


The total length of the data fields of the j j 
associated with a load module cannot exceed 32K (32768) 
bytes. To determine the number of bytes of identification data 
ily a in a particular load module, use the following 
ormula: 


SIZE = 269 + 16A + 31B + 2C + In + 6) 

where: 

A= the number of compilations or assemblies by a processor 
supporting CSECT identification that produced the object 
code for the module. 

B= the number of preprocessor compiler compilations by a 
processor supporting CSECT identification that produced 
the object code for the module. 


C= the number of control sections in the module with END 
statements that contain identification data. 


I= the number of control sections in the module that contain 
user~supplied data supplied during link-editing by the 
optional IDENTIFY control statement. 

n= the average number of characters in the data specified by 


IDENTIFY control statements. 
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Intermediate Data Set 


Notes: 


1. The size computed by the formula includes space for a 
recording up to 19 HMASPZAP modifications. When 75% of this Na” 
space has been used, a new 25l-byte record is created the 
next time the module is reprocessed by the linkage editor. 


2. To determine the approximate number of records involved, 
divide the computed size of the identification data by 256. 


EXAMPLE: A module contains 100 control sections produced by 20 
unique compilations. Each control section is identified during 
link-editing by 8 characters of user data specified by the 
IDENTIFY control statement. The size of the identification data 
is computed as follows: 


A = 20 
I = 100 
n= 8 


269 + 320 + 1400 = 1989 bytes 


If the optional user data specified on the IDENTIFY control 
statements is omitted, the size can be reduced considerably, as 
computed below: 


269 + 320 = 589 bytes 


The maximum number of downward calls made from a segment to 

other segments lower in its path can never exceed 340. To 

compute the maximum number of downward calls allowed, subtract 

12 from the SYSLMOD record size and then divide the difference 

by 12. Examples of maximum downward calls are 84 for a SYSLMOD 

Age rae of 1024 bytes and 340 for a SYSLMOD record size of 
ytes. 


The intermediate data set (SYSUT]1) is used by the linkage editor 
to hold intermediate data records during processing. The 
linkage editor places intermediate data in this data set when 
storage allocated for input data or certain forms of 
out-of-sequence text is exhausted. 


The following direct access devices, if supported by the system, 
can be used for this data set: 


IBM 2305-2 Fixed Head Storage 


IBM 3330 Disk Storage 

IBM 3330-11 Disk Storage 

IBM 3340 Direct Access Storage 
IBM 3344 Direct Access Storage 
IBM 3350 Direct Access Storage 
IBM 3375 Direct Access Storage 
IBM 3380 Direct Access Storage 
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Ordinarily, when a load module produced by the linkage editor is 
executed, all the control sections of the module remain in 
virtual storage throughout execution. The length of the load 
module is, therefore, the sum of the lengths of all the control 
sections. When storage space is not at a premium, this is the 
most efficient way to execute a program. However, if a program 
approaches the limits of the virtual storage available, the 
programmer should consider using the overlay facilities of the 
linkage editor. 


In most cases, all that is needed to convert an ordinary program 
to an overlay program is the addition of control statements to 
structure the module. The programmer chooses the overlayable 
portions of the program, and the system arranges to load the 
required portions when needed during execution of the program. 





When the linkage editor overlay facility is requested, the load 
module is structured so that, at execution time, certain control 
sections are loaded only when referenced. When a reference is 
made from an executing control section to ancther, the system 
determines whether or not the code required is already in 
virtual storage. If it is not, the code is loaded dynamically 
i may overlay an unneeded part of the module already in 
storage. 





The rest of this chapter is divided into three sections that 
describe the design, specification, and special considerations 
for overlay programs. 


The way in which an overlay module is structured depends on the 
relationships among the control sections within the module. Two 
control sections that do not have to be in storage at the same 
time can overlay each other. Such control sections are 

n 3; that is, they do not reference each other either 
directly or indirectly. Independent control sections can be 
assigned the same load addresses and are loaded only when 
referenced. For example, control sections that handle error 
conditions or unusual data may be used infrequently, and need 
not be occupying storage unless in use. 


Control sections are grouped into segments. A seaqment is the 
smallest functional unit Cone or more control sections) that can 
be loaded as one logical entity during execution. The control 
sections required all the time are grouped into a special 
segment called the root seqment. This segment remains in 
storage throughout execution of an overlay program. 


When a particular segment is to be executed, any segments 
between it and the root segment must also be in storage. This 
is a path. A reference from one segment to another segment 
lower ina path is a downward reference (see "Control Section 
Dependency" on page 16494). That is, the segment contains a 
reference to another segment farther from the root segment. 
Conversely, a reference from one segment to another segment 
higher ina path (closer to the root segment) is an 


Therefore, a downward reference may cause overlay, because the 
necessary segment may not yet be in virtual storage. An upward 
reference will not cause overlay, because all segments between a 
segment and the root segment must be present in storage. 





Sometimes several paths need the same control sections. This 
problem may be solved by placing the control sections in another 
region. In an overlay structure, a region is a contiguous area 
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of virtual storage within which segments can be loaded 
independently of paths in other regions. An overlay program can 
be designed in single or multiple regions. 


SINGLE REGION OVERLAY PROGRAM 


To design an overlay structure, the programmer should select 
those control sections that will receive control at the 

beginning of execution, plus those that should always remain in 
storage; these control sections form the root segment. The rest 
of the structure is developed by determining the dependencies of 
the remaining control sections and how they can use the same 
virtual storage locations at different times during execution. 


Besides control section dependency, other topics discussed in 
this section are segment dependency, the length of the overlay 
program, segment origin, communication between segments, and 
overlay processing. 


Control Section Dependency 


Control section dependency is determined by the requirenents of 
a control section for a given routine in another control 
section. A control section is dependent upon any control 
section from which it receives control, or which processes its 
data. For example, if control section C receives control from 
control section B, then C is dependent upon B. That is, both 
control sections must be in storage before execution can 
continue beyond a given point in the program. 


Assume that a program contains seven control sections, CSA 
through CSG, and exceeds the amount of storage available for its 
execution. Before the program is rewritten, it is examined to 
see whether or not it could be placed into an overlay structure. 
Figure 61 on page 165 shows the groups of dependent control 
sections in the program (the arrows indicate dependencies). 
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CSC | CSC | CSG | 
Dependent 
Group 3 
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CSD | CSF | 
Dependent 
ee Group 2 
CSE | 
Dependent 
Group 1 


Figure 61. Control Section Dependencies 





Each dependent group is also a path. That is, if control 
section CSG is to be executed, CSB and CSA must also be in 
storage. Because CSA and CSB are in each path, they must be in 
the root segment. Control section CSC is in two groups, and 
therefore is a common segment in two different paths. 


A better way to show the relationship between segments is with a 
tree structure. A tree is the graphic representation that shows 
how segments can use virtual storage at different times. It 
does not imply the order of execution, although the root segment 
is the first to receive control. Figure 62 on page 166 shows 
the tree structure for the dependent groups shown in Figure 61. 
The structure is contained in one region, and has five segments. 
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Figure 62. Single-Region Overlay Tree Structure 





Segment Dependency 


When a segment is in virtual storage, all segments in its path 
are also in virtual storage. Each time a segment is loaded, all 
segments in its path are loaded if they are not already in 
virtual storage. In Figure 62, when segment 3 is in virtual 
storage, segments 1 and 2 are also in virtual storage. However, 
if segment 2 is in storage, this does not imply that segment 3 
or 4 is in virtual storage, because neither segment is in the 
path of segment 2. 


The position of the segments in an overlay tree structure does 
not imply the sequence in which the segments are executed. A 
segment can be loaded and overlaid as many times as required by 
the logic of the program. However, a segment will not be 
overlaid by itself. If a segment is modified during execution, 
that modification remains only until the segment is overlaid 
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Length of an Overlay Program 


For purposes of illustration, assume that the control sections 
in the sample program have the following lengths: 


Control Section Length (Cin bytes) 





If the program were not in overlay, it would require 32000 bytes 
of virtual storage. In overlay, however, the program requires 
the amount of storage needed for the longest path. In this 
structure, the longest path is formed by segments l, 2, and 3, 
Since, when they are all in storage, they require 18000 bytes, 
as shown in Figure 63 


CSA 
3,000 


byt 
a Root Segment 1 
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Figure 63. Length of an Overlay Module 
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Segment Origin 


Note: The length of the longest path is not the minimum 
requirement for an overlay program; when a program is in 
overlay, certain tables are used, and their storage requirements 
must also be considered. The storage required by these tables 
is given in the section "Special Considerations" on page 182. 


The linkage editor assigns the relocatable origin of the root 
segment (the origin of the program) at 0. The relative origin 
of each segment is determined by 0 plus the length of all 
segments in the path. For example, the origin of segments 3 and 
G4 is equal to 0 plus 6000 (the length of segment 2) plus 5000 
(the length of the root segment), or 11000. The origins of all 
the segments are as follows: 





The segment origin is also called the load point, because it is 
the relative location at which the segment is loaded. 


Figure 64 on page 169 shows the segment origin for each segment 
and the way storage is used by the sample program. In the 
illustration, the vertical bars indicate segment origin; any two 
segments with the same origin may use the same storage area. 
Ay oF ares shows that the longest path is that of segments 

, ry» an . 
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Figure 64. Segment Origin and Use of Storage 





Communication between Segments 


Segments that can be in virtual storage simultaneously are 
considered to be inclusive. Segments in the same region but not 
in the same path are considered to be exclusive; they cannot be 
in virtual storage simultaneously. Figure 65 on page 170 shows 
the inclusive and exclusive segments in the sample program. 
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Figure 65. Inclusive and Exclusive Segments 





Segments upon which two or more exclusive segments are dependent 
are called common segments. A segment common to two other 
segments is part of the path of each segment. Figure 65, 
segment 2 is common to segments 3 and 4, but not to segment 5. 


An anclusive reference is a reference between inclusive 
segments; that 1s, a reference from a segment in storage to an 
external symbol in a segment that will not cause overlay of the 
calling segment. An exclusive reference is a reference between 
exclusive segments; that is, a reference from a segment in 
storage to an external symbol in a segment that will cause 
overlay of the calling segment. 


Figure 66 on page 171 shows the difference between an inclusive 
reference and an exclusive reference; the arrows indicate 
references between segments. 


INCLUSIVE REFERENCES: Wherever possible, inclusive references 
should be used instead of exclusive references. Inclusive 
references between segments are always valid and do not require 
special options. When inclusive references are used, there is 
also less chance for error in structuring the overlay program 
correctly. 


EXCLUSIVE REFERENCES: An exclusive reference is made when the 
external reference in the requesting segment is to a symbol 
defined in a segment not in the path of the requesting segment. 
Exclusive references are either valid or invalid. 


An exclusive reference is valid only if there is also an 
inclusive reference to the requested control section ina 
segment common to both the segment to be loaded and the segment 
to be overlaid. The same symbol must be used in both the common 
segment and the exclusive reference. In Figure 66 on page 171, 
a reference from segment B to segment A is valid, because there 
is an inclusive reference from the common segment to segment A. 
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CAn entry table in the common segment contains the address of 
segment A; the overlay does not destroy this table.) 








Inclusive 
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Segment A 
Exclusive 
Reference 
( | Figure 66. Inclusive and Exclusive References 


In the same illustration, a reference from segment A to segment 
B is invalid, because there is no reference from the common 
segment to segment B. A reference from segment A to segment B 
can be made valid by including, in the common segment, an 
external reference to the symbol used in the exclusive reference 
to segment B 


Another way to eliminate exclusive references is to arrange the 
program so that the references that will cause overlay are made 
in a higher segment. For example, the programmer could 
eliminate the exclusive reference shown in Figure 66 by writing 
a new module to be placed in the common segment; the new 
module's only function would be to reference segment B. The 
code in segment A could then be changed to refer to the new 
module instead of to segment B. Control then would pass from 
segment A to the common segment, where the overlay of segment A 
by segment B would be initiated. 


If either valid or invalid exclusive references appear in the 
program, the linkage editor considers them errors unless one of 
the special options is used. These options are described later 
in this section (see "Special Considerations" on page 182). 


Notes: 


1. During the execution of a program written in a higher level 
language such as FORTRAN, COBOL, or PL/I, an exclusive call 
results in abnormal termination of the program if the 
requested segment attempts to return control directly to the 
invoking segment that has been overlaid. 


2. If a program written in COBOL includes a segment that 
contains a reference to a COBOL class test or TRANSFORM 
table, the segment containing the table must be either (1) 
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Overlay Process 


CSD 


Segment 3 


CSE 








in the root segment or (2) a segment that is higher in the 
qoue path than the segment containing. the reference to the 
able. | 


The overlay process is initiated during execution of a program 
only if a control section in virtual storage references a 
control section not in storage. The control program determines 
the segment that the referenced control section is in and, if 
necessary, loads the segment. When a segment is loaded, it 
overlays any segment in storage with the same relative origin. 
Any segments in storage that are lower in the path of the | 
overlaid segment may also be overlaid. An exclusive reference 
can also cause segments higher in the path to be overlaid. Ifa 
control section in storage references a control section in 
another segment already in storage, no overlay occurs. 


The portion of the control program that determines when overlay 
is to occur is the overlay supervisor, which uses special tables 
to determine when overlay is necessary. These tables are 

generated by the linkage editor, and are part of the output load 
module. The special tables are the segment table and the entry 


 table€s). Figure 67 shows the location of the segment and entry 


tables in the sample program. 
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Figure 67. Location of Segment and Entry Tables in an Overlay Module 
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Because the tables are present in every overlay module, their 
Size must be considered when planning the use of virtual 
storage. The storage requirements for the tables are given in 
"Special Considerations" on page 182. A more detailed 
discussion of the segment and entry tables follows. 


SEGMENT TABLE: Each overlay program contains one segment table 
CSEGTAB); this table is the first control section in the root 
segment. The segment table contains information about the 
relationship of the segments and regions in the program. During 
execution, the table also indicates which segments are either in 
storage or being loaded, and other control information. 


ENTRY TABLE: Each segment that is not the last segment in a 
path may contain one entry table CENTAB); this table, when 
present, is the last control section in a segment. 


When overlay will be required, an entry in the table is created 
fora symbol to which control is to be passed, provided (1) the 
symbol is used as an external reference in the requesting 
segment, and (2) the symbol is defined in another segment either 
lower in the path of the requesting segment, or in another 
region. An ENTAB entry is not created for any symbol already 
present in an entry table closer to the root segment Chigher in 
the path), or for a symbol defined higher in the path 

reference to a symbol higher in the path does not have to go 
through the control program because no overlay is required. ) 


If an external reference and the symbol to which it refers are 
in segments not in the same path but in the same region, an 
exclusive reference was made. If the exclusive reference is 
valid, an ENTAB entry for the symbol is present in the common 
segment. Because the common segment is higher in the path of 
the requesting segment, no ENTAB entry is created in the 
requesting segment. When the reference is executed, control 
passes through the ENTAB entry in the common segment. That is, 
a branch to the location in the ENTAB entry causes the overlay 
supervisor to be called to load the needed segment or segments. 


If the exclusive reference is invalid, no ENTAB entry is present 
in the common segment. If the LET option is specified, an 
invalid exclusive reference causes unpredictable results when 
the program is executed. Because no ENTAB entry exists, control 
is passed directly to the relative address specified in the 
reference, even though the requested segment may not be in 
virtual storage. 


MULTIPLE REGION OVERLAY PROGRAM 


If a control section is used by several segments, it is usually 
desirable to place that control section in the root segment. 
However, the root segment can get so large that the benefits of 
overlay are lost. If some of the control sections in the root 
segment could overlay each other Cexcept for the requirement 
that all segments in a path must be in storage at the same 
time), the job may be a candidate for multiple region structure. 
Multiple region structures can also be used to increase segment 
loading efficiency: Processing can continue in one region while 
the next path to be executed is being loaded into another 
region. 


With multiple regions, a segment has access to segments that are 
not in its path. Within each region, the rules for single 
region overlay programs apply, but the regions are independent 
of each other. A maximum of four regions can be used. 


Figure 68 on page 174 shows the relationship between the control 
sections in the sample program and two new control sections, CSH 
and CSI. The two new control sections are each used by two 
other control sections in different paths. Placing CSH and CSI 
in the root segment makes the segment larger than necessary, 
because CSH and CSI can overlay each other. The two control 
sections should not be duplicated in two paths, because the 
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linkage editor automatically deletes the second pair and an 
invalid exclusive reference may then result. 7 
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Figure 68. Control Sections Used by Several Paths 





If, however, the two control sections are placed in another 
region, they can be in virtual storage when needed, regardless 
of the path being executed in the first region. Figure 69 on 
page 175 shows all the control sections in a two-region 
structure. Either path in region 2 can be in virtual storage 
regardless of the path being executed in region 1; segments in 
region 2 can cause segments in region 1 to be loaded without 
being overlaid themselves. 
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Figure 69. Overlay Tree for Multiple-Region Program 


The relative origin of a second region is determined by the 
length of the longest path in the first region (18000 bytes). 
Region 2, therefore, begins at 0 plus 18000 bytes. The relative 
origin of a third region would be determined by the length of 
the longest path in the first region plus the longest path in 
the second region. 


The virtual storage required for the program is determined by 
adding the lengths of the longest path in each region. n 
Figure 69, if CSH is 4000 bytes and CSI is 3000 bytes, the 
storage required is 22000 bytes, plus the storage required by 
the special overlay tables. 


Care should be exercised when choosing multiple regions. There 
may be some system degradation caused by the overlay supervisor 
being uneere to optimize segment loading when multiple regions 
are used. 
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SPECIFICATION OF AN OVERLAY PROGRAM 


SEGMENT ORIGIN 


Once the programmer has designed an overlay structure, the 
module must be placed in that structure by indicating to the 


ye 
~ 


linkage editor the relative positions of the segments and 
regions, and the control sections in each segment. Positioning 
is accomplished as follows: 

e Segments are positioned by OVERLAY statements. Because 


segments are not named, the programmer identifies a segment 
by giving its origin Cor load point) a symbolic name and 
then uses that name in an OVERLAY statement to specify a 


symbolic origin. 


Each OVERLAY statement begins a new 


segment. 


e Regions are also positioned by OVERLAY statements. The 
programmer specifies the origin of the first segment of the 
region, followed by the word REGION in parentheses. 


the 


input sequence. 
sections within a 


are positioned in the segment specified by 
OVERLAY statement with which they are associated in the 
However, the sequence of the control 
segment is not necessarily the order in 


which the control sections are specified. 


The input sequence of control statements and control sections 
should reflect the sequence of the segments in the overlay 
structure from top to bottom, left to right, and region by 


region. 


This sequence is illustrated in later examples. 


In addition, several special options are used with overlay 


programs. 


These options are specified on the EXEC statement for 


the linkage editor job step, and are described at the end of 
this section. 


Note: 


If a load module in overlay structure is to be 


reprocessed by the linkage editor, the OVERLAY statements and 


special 


options (such as OVLY) must be respecified. If the ae 


statements and options are not provided, the output load module 
will not be in overlay structure. 


The symbolic origin of every segment, other than the root 


segment, must be specified with an OVERLAY statement. 


The first 


time a symbolic origin is specified, a load point is created at 


the end 


of the previous segment. That load point is logically 


assigned a relative address at the doubleword boundary that 


follows 


the last byte in the preceding segment. Subsequent use 


of the same symbolic origin indicates that the next segment is 


to have 


its origin at the same load point. 


In the sample single-region program, the symbolic origin names 


ONE and 


shown in Figure 69 on page 175. 


TWO are assigned to the two necessary load points, as 
Segments 2 and 5 are at load 


point ONE; segments 3 and 4@ are at load point TWO. 


The following sequence of OVERLAY statements will result in the 


structure in Figure 


segment 


Control 
Control 
OVERLAY 
Control 
OVERLAY 
Control 
Control 
OVERLAY 
Control 


OVERLAY ONE 


Control 


70 on page 177 (the control sections in each 
are indicated by name): 


section CSA 

section CSB 

ONE 

section CSC 

TWO 

section CSD 

section CSE 

TWO i 
section CSF ane 
section CSG 
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Note: The sequence of OVERLAY statements reflects the order of 
segments in the structure from top to bottom and left to right. 





Root Segment 1 


ONE 


Segment 2 
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Segment 3 Segment 4 
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Figure 70. Symbolic Segment Origin in Single-Region Program 


REGION ORIGIN 


The symbolic origin of every region, other than the first, must 
be specified with an OVERLAY statement. Once a new region is 
specified, a segment origin from a previous region should not be 
specified. 


In the sample multiple-region program, the symbolic origin THREE 


is assigned to region 2, as shown in Figure 71 on page 178 
Segments 6 and 7 are at load point THREE. 


Appendix C. Designing and Specifying Overlay Programs 177 

















1 
rsh ’ 


REGION 1 | % 


Root Segment 1 


ONE 
Segment 2 
Segment 5 
TWO 
Segment 4 
Segment 3 i 
od THREE 
REGION 2 
Segment 7 
Segment 6 


| 


Figure 71. Symbolic Segment and Region Origin in Multiple-Region Program 


If the following is added to the sequence for the single-region 
program, the multiple-region structure will be produced: 


OVERLAY THREECREGION) 
Control section CSH 
OVERLAY THREE. 
Control section CSI 


POSITIONING CONTROL SECTIONS 
After each OVERLAY statement, the control sections for that 
segment must be specified. The control sections for a segment 


can be specified in one of three ways: 


e By placing the object decks for each segment after the 
appropriate OVERLAY statement 


By using INCLUDE control statements for the modules 
containing the control sections for the segment 


® By using INSERT control statements to reposition a control 
section from its position in the input stream to a 
particular segment 


Any control sections that precede the first OVERLAY statement f™ 
are placed in the root segment; they can be repositioned with an i 
INSERT statement. Control sections from the automatic call <a 


library are also placed in the root segment. The INSERT 
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statement can be used to place these control sections in another 
et specific segment. Common areas in an overlay program are 
( described in "Special Considerations" on page 182. 


An example of each of the three methods of positioning control 
sections follows. Each example results in the structure for the 
Single-region sample program. An example is also given of 
repositioning control sections from the automatic call library. 


Using Object Decks 


The primary input data set for this example contains an ENTRY 
statement and seven object decks, separated by OVERLAY 
statements: 


| “/LKED EXEC PGM=HEWL,PARM=*OVLY' 


//7SYSLIN DD 
ENTRY BEGIN. 
Object deck for 
Object deck for 
OVERLAY ONE. 
Object deck for 
OVERLAY TWO. 
Object deck for 
Object deck for 
OVERLAY TWO. 
Object deck for 
OVERLAY ONE. 

Object deck for 
/* 





The EXEC statement illustrates that the OVLY parameter must be 
specified for every overlay program to be processed by the 
linkage editor. 


Using INCLUDE Statements 


The primary input data set for this example contains a series of 
control statements. The INCLUDE statements in the primary input 
data set direct the linkage editor to library members that 
contain the control sections of the program. 


//LKED EXEC PGM=HEWL,PARM='OVLY* 


//MODLIB DD DSNAME=OBJLIB,DISP=COLD,KEEP),... 
S/SYSLIN DD x 

ENTRY BEGIN 

INCLUDE MODLIBCCSA,CSB) 

OVERLAY ONE 


INCLUDE MODLIBCCSC) 
OVERLAY TWO 
INCLUDE MODLIBCCSD,CSE) 
OVERLAY TWO 
INCLUDE MODLIBCCSF) 
OVERLAY ONE 

( INCLUDE MODLIBCCSG) 
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This example differs from the previous one in that the control 
sections of the program are not part of the primary input data Sieh: 
set, but are represented in the primary input by the INCLUDE 


statements. When an INCLUDE statement is processed, the 
hid ae control section is retrieved from the library and | 
processed. 


Using INSERT Statements 


When INSERT statements are used, the INSERT and OVERLAY 
statements may either follow or precede all the input modules. 
However, the order of the control sections in a segment is not 
necessarily the same as the order of the INSERT statements for 
each segment. An example of each is given, as well as an 
example of repositioning automatically called control sections. 


FOLLOWING ALL INPUT: The control statements can follow all the 
input modules, as shown in the following example: 


//LKED EXEC PGM=HEWL,PARM=‘OVLY'* 


S/SYSLIN DD DSNAME=OBJECT, DISP=COLD,KEEP),... 
// DD R 


ENTRY BEGIN 
INSERT CSA,CSB 
OVERLAY ONE 
INSERT CSC 
OVERLAY TWO 
INSERT CSD,CSE 
OVERLAY TWO 
INSERT CSF 
QVERLAY ONE 
INSERT CSG 





The primary input data set contains the object modules for the 
control sections, and the input stream is concatenated to it. 


PRECEDING ALL INPUT: The control statements can also precede 
all input modules, as shown in the following example: 


//ULKED EXEC PGM=HEWL,PARM='OVLY' 
//MODULES DD DSNAME=OBJSEQ, DISP=COLD,KEEP),... 


| Z/ASYSLIN DD 
ENTRY BEGIN 
INSERT CSA,CSB 
OVERLAY ONE 
INSERT CSC 
OVERLAY TWO 
INSERT CSD,CSE 
OVERLAY TWO 
INSERT CSF 
OVERLAY ONE 
INSERT CSG 
INCLUDE MODULES 
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OVLY Option 





The primary input data set contains all the control statements 
for the overlay structure and an INCLUDE statement. The data 
set specified by the INCLUDE statement contains all the object 
modules for the structure, and is a sequential data set. 


REPOSITIONING AUTOMATICALLY CALLED CONTROL SECTIONS: The INSERT 
statement can also be used to move automatically called control 
sections from the root segment to the desired segment. This is 
helpful when control sections from the automatic call library 
are used in only one segment. By moving such control sections, 
the root segment will contain only those control sections used 
by more than one segment. 


When a program is written in a higher level language, special 
control sections are called from the automatic call library. 
Assume that the sample program is written in COBOL and that two 
control sections CILBOVTRO and ILBOSCHO) are called 
automatically from SYS1.COBLIB. Ordinarily, these control 
sections are placed in the root segment. However, INSERT 
statements are used in the following example to place these 
control sections in segments other than the root segment. 


//LKED EXEC PGM=HEWL,PARM='OVLY' 
| “/MODLIB DD DSNAME=OBJLIB, DISP=(OLD,KEEP),... 
S/SYSLIB DD DSNAME=SYS1.COBLIB, DISP=SHR 


//SYSLIN DD x 
ENTRY BEGIN 
INCLUDE MODLIBCCSA,CSB) 
OVERLAY ONE 
INCLUDE MODLIBCCSC) 
OVERLAY TWO 
INCLUDE MODLIBCCSD,CSE) 
INSERT ILBOVTRO 
OVERLAY TWO 
INCLUDE MODLIBC(CSF) 
INSERT ILBOSCHO 
OVERLAY ONE 
INCLUDE MODLIBCCSG) 





As a result, segments 3 and 4 will also contain ILBOVTRO and 
ILBOSCHO, respectively. 


This example also combines two of the ways of specifying the 
control sections for a segment. 


The linkage editor provides three special job step options 
COVLY, LET, and XCAL) for the overlay programmer. These options 
are specified on the EXEC statement for the linkage editor job 
step. They must be specified each time a load module in overlay 
structure is reprocessed by the linkage editor. 


The OVLY option must be specified for every overlay program. If 
the option is omitted, all the OVERLAY and INSERT statements are 
considered invalid. Unless the LET option is specified, the 
output module is marked not executable. The output module is 
not in an overlay structure. 
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With the LET option, the output module is marked executable even 
though certain error conditions were found during linkage editor 
processing. When LET is specified, any exclusive reference 
valid or invalid) is accepted. At execution time, a valid 
exclusive reference is executed correctly; an invalid exclusive 
reference usually causes unpredictable results. 


Also with the LET option, unresolved external references do not 
prevent the module from being marked executable. This could be 
helpful when part of a large program is ready for testing; the 
segments to be tested may contain references to segments not yet 
coded. If LET is specified, the program can be executed to test 
those parts that are finished Cas long as the references to the 
absent segments are not executed). If the LET option is not 
specified, these unresolved references will cause the module to 
be marked not executable. 


With the XCAL option, a valid exclusive call is not considered 
an error, and the load module is marked executable. However, 
unless the LET option is specified, other errors could cause the 
module to be marked not executable. In this case, the XCAL 
option is not required. 


AMODE and RMODE Options 


If the OVLY option is specified, the AMODE and RMODE options are 
ignored and a diagnostic message is issued to that effect. 
Overlay programs are assigned a residence mode of 24 and an 
addressing mode of 24 


SPECIAL CONSIDERATIONS 


CONMON AREAS 


This section discusses several special considerations that 

affect overlay programs. These considerations include the 

handling of common areas, special storage requirements, and 
overlay communication. 


Wher; common areas (blank or named) are encountered in an overlay 
program, the common areas are collected as described previously 
(that is, the largest blank or identically named common area is 
used). The final location of the common area in the output 
module depends on whether INSERT statements were used to 
structure the program. 


If INSERT statements are used to structure the overlay program, 

a named common area should either be part of the input stream in 
the segment to which it belongs, or should be placed there with 

an INSERT statement. 


Because INSERT statements cannot be used for blank common areas, 
a blank common area should always be part of the input stream in 
the segment to which it belongs. 


If INSERT statements are not used, and the control sections for 
each segment are placed or included between OVERLAY statements, 
the linkage editor "promotes" the common area automatically. 
That is, the common area is placed in the common segment of the 
paths that contain references to it so that the common area is 
in storage when needed. The position of the promoted area in 
relation to other control sections within the common segment is 
unpredictable. 
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If a common area is encountered in a module from the automatic 

call library, automatic promotion places the common area in the 
root segment. In the case of a named common area, this may be 

overridden by use of the INSERT statement. 





Assume that the sample program is written in FORTRAN and that 
common areas are present as shown in Figure 72. Further assume 
that the overlay program is structured with INCLUDE statements 
between the OVERLAY statements so that automatic promotion 








occurs. 
CSA 
+ Root Segment 1 
CSB 
Blank Common Blank Common 
Segment 2 
CSG Segment 5 
CSC 
Named Common B 
Named Common A Named Common A 
7 CSD 
T Segment 3 CSE Segment 4 
CSE 


Named Common B 


Figure 72. Common Areas before Processing 


Segments 2 and 5 contain blank common areas, segments 3 and 4 
contain named common area A, and segments 4 and 5 contain named 
common area B. During linkage editor processing, the blank 
common areas are collected and the largest area is promoted to 
the root segment (the first common segment in the two paths); 
the common areas named A are collected and the largest area is 
promoted to segment 2; the common areas named B are collected 
and promoted to the root segment. Figure 73 on page 184 shows 
hat rotate of the common areas after processing by the linkage 
editor. 
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Figure 73. Common Areas after Processing 





STORAGE REQUIREMENTS 


The virtual storage requirements for an overlay program include 
the items placed in the module by the linkage editor and the 
overlay supervisor necessary for execution. 


ITEMS IN THE LOAD MODULE: The items that the linkage editor 
places in an overlay load module are the segment table, entry 
tables, and other control information. Their size must be 
included in the minimum requirements for an overlay program, 
along with the storage required by the longest path and any 
control sections from the automatic call library. 


Every overlay program has one segment table in the root segment. 
The storage requirements are: 


SEGTAB = Gn + 24 


where: 


n = the number of segments in the program 
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Some segments will have an entry table. The requirements of the 
entry tables in the segments in the longest path must be added 
to the storage requirements for the program. The requirements 
for an entry table are: 


ENTAB = 12¢x + 1) 





where: 
x = the number of entries in the table 


Finally, a NOTE list is required to execute an overlay program. 
The storage requirements are: 


NOTELST = Gn + 8 





where: 
n = the number of segments in the program 


OVERLAY SUPERVISOR: To the minimum requirements of the load 
module itself must be added the requirements of the overlay 
supervisor. This system routine is not placed in an overlay 
module, but, during execution of the module, the supervisor may 
be called to initiate an overlay. If called, the storage 
allocated for the program must also be large enough for the 
supervisor. 








This asynchronous overlay supervisor module is furnished with 
the system. This asynchronous module also permits overlay 
through the SEGLD macro instruction (see "Overlay 
Communication"). The storage requirement for the overlay 
supervisor module is 180 bytes. 


( OVERLAY COMMUNICATION 


Several ways of communicating between segments of an overlay 
program are discussed in this section. A higher level or 
Assembler language program may use a CALL statement or a CALL 
macro instruction, respectively, to cause control to be vassed 
to a symbol defined in another segment. The CALL may cause the 
segment to be loaded if it is not already present in storage. 

An Assembler language program may also use three additional ways 
to communicate between segments: 


e By a branch instruction, which causes a segment to be loaded 
and ee to be passed to a symbol defined in that 
segment. 


e By a segment load (SEGLD) macro instruction, which requests 
loading of a segment. Processing continues in the 
eae segment while the requested segment is being 

oaded. 


e By a segment load and wait (SEGWT) macro instruction, which 
requests loading of a segment. Processing continues in the 
cesge ane segment only after the requested segment is 

oaded. 


Any of the four methods may be used to make inclusive 
references. Only the CALL and branch may be used to make 
exclusive references. Neither the SEGLD nor the SEGWT macro 
instruction should be used to make exclusive references; because 
both imply that processing is to continue in the requesting | 
segment, an exclusive reference leads to erroneous results when 
the program is executed. 
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CALL Statement or CALL Macro Instruction 


Branch Instruction 


A CALL statement or a CALL macro instruction refers to an 
external name in the segment to which control is to be passed. 
The external name must be defined as an external reference in 
the requesting segment. In Assembler language, the name must be 
defined as a 4-byte V-type address constant; the high-order bit 
is reserved for use by the control program, and must not be 
altered during execution of the program. 


When a CALL is used, the requested segment and any segments in 
its path are loaded if they are not part of the path already in 
virtual storage. After the segment is loaded, control is passed 
to the requested segment at the location specified by the 
external name. 


A CALL between inclusive segments is always valid. A return can 
be made to the requesting segment by another source language 
statement, such as RETURN. A CALL between exclusive segments is 
valid if the conditions for a valid exclusive reference are met; 
a return from the requested segment can be made only by another 
eee RIS reference, because the requesting segment has been 
overlaid. 


Any of the branching conventions shown in Figure 74 on page 187 
can be used to request loading and branching to a segment. As a 
result, the requested segment and any segments in its path are 
loaded if they are not part of the path already in virtual 
storage. Control is then passed to the requested segment at the 
location specified by the address constant placed in general 
register 15 
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Example Namet Operation Operand2, 3 

1 L R15,=VCname) 
BALR Rn,R15 

2 L R15,ADCON 
BALR Rn,R15 

ADCON DC VCname) 

3 L R15,=VCname) 
BAL Rn,0C0,R15)4 

G L R15,=VCname) 
BAL Rn, 0CR15)5 

56 L R15,=VCname) 
BCR 15,R15 

6¢ L R15,=VCname) 
BC 15,0€0,R15)4 

76 L R15,=VCname) 
BC 15,0(R15)5 

Figure 74. Branch Sequences for Overlay Programs 


Notes to Figure 74: 


i When the name field is blank, specification of a name is 
optional. 


2 R15 must hold a 4-byte address constant that is the address 
of an entry name or a control section name in the requested 
segment. The address constant must be loaded into the 
standard entry point register, register 15. 


§ Rn is any other register and is used to hold the return 
address. This register is usually register 14 


“4 This may also be written so that the index register is loaded 
with the address constant; the other fields must be zero. 


> In this format, the base register must be loaded with the 
address constant; the displacement must be zero. 


6 This example is an unconditional branch; other conditions are 
also allowed. : 


The address constant must be a 4-byte VY-type address constant. 
The high-order bit is reserved for use by the control program, 
and must not be altered during execution of the program. 


A branch between inclusive segments is always valid; a return 
may be made by means of the address stored in Rn. A branch 
between exclusive segments is valid if the conditions for a 
valid exclusive reference are met; a return can be made only by 
another exclusive reference. 


Appendix C. Designing and Specifying Overlay Programs 187 


Segment Load (SEGLD) Macro Instruction 


The SEGLD macro instruction is used to provide overlap between 
segment loading and processing within the requesting segment. | 
As a result of using any of the examples in Figure 75, the 
loading of the requested segment and any segments in its path is 
initiated when they are not part of the path already in virtual 
storage. Processing then resumes at the next sequential 
instruction in the requesting segment while the segment or 
segments are being loaded. Control may be passed to the 
requested segment with either a CALL or a branch, as shown in 
Examples 1 and 2, respectively. A SEGWT instruction can be used 
to ensure that the data in the control section specified by the 
external name is in virtual storage before processing resumes, 
as shown in Example 3. 


Example Name Operation Operand2, $ 


l | SEGLD external name 
CALL external name 

2 SEGLD external name 
branch external name 

3 SEGLD external name 
SEGWT external name 
L Rn, =VC name) 


Figure 75. Use of the SEGLD Macro Instruction 


Notes to Figure 75: 


1 When the name field is blank, specification of a name is 
optional. 


External name is an entry name or a control section name in 
the requested segment. 


¢ Rn is any other register and is used to hold the return 
address. This register is usually register 14 


The external name specified in the SEGLD macro instruction must 
be defined with a 4-byte V-type address constant. The 
high-order bit is reserved for use by the control program and 
must not be altered during execution of the program. 


Segment Wait (SEGWT) Macro Instruction 


The SEGWT macro instruction is used to stop processing in the 
peatesssy segment until the requested segment is in virtual 
storage. 


As a result of using any of the examples in Figure 76 on 

page 189, no further processing takes place until the requested 
segment and all segments in its path are loaded when not already 
in virtual storage. Processing resumes at the next sequential 
instruction in the requesting segment after the requested 
segment has been loaded. 
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Example Namel Operation Operand2,3 


l SEGLD external name 
SEGNT external name 
L Rn, ADCON 
branch 
ADCON DC VC name) 
2 SEGNT external name 
L Rn, =VCname) 


Figure 76. Use of the SEGNT Macro Instruction 








Notes to Figure 76: 


1 When the name field is blank, specification of a name is 
optional. 





External name is an entry name or a control section name in 
the requested statement. 


6 Rn is any other register and is used to hold the return 
address. This register is usually register 14. 


If the SEGNT and SEGLD macro instructions are used together, 
overlap occurs between processing and segment loading; use of 
the SEGWT macro instruction serves as a check to see that the 
necessary information is in storage when it is finally needed 
(see Example 1 in Figure 76). In Example 2 in Figure 76, no 
overlap is provided; the SEGWT macro instruction initiates 
loading, and processing is stopped in the requesting segment 
until the requested segment is in virtual storage. 


The external name specified in the SEGWT macro instruction must 
be defined with a 4~byte V-type address constant. The 
high-order bit is reserved for use by the control program, and 
must not be altered during execution of the program. 


If the contents of a virtual storage location in the requested 


segment are to be processed, the entry name of the location must 
be referred to by an A-type address constant. 
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ee loader requires virtual storage space for the following 
items: 


° Loader code 

° Data management access methods 

e Buffers and tables used by the loader (dynamic storage) 
e Loaded program (dynamic storage) 


Region size includes all four of the above items; the SIZE 
option refers to the last two items. 


For the SIZE option, the minimum required virtual storage is 4K 
bytes plus the size of the loaded program. This minimum 
requirement grows to accommodate the extra table entries needed 
by the program being loaded. For example, FORTRAN requires at 
least 3K bytes plus GK bytes plus the size of the loaded 
program, and PL/I needs at least 8K bytes plus 4K bytes plus the 
size of the loaded program. Buffer number (BUFNO) and block 
size (BLKSIZE) could also increase this minimum size. Figure 77 
on page 191 shows the appropriate storage requirements in bytes. 


The maximum virtual storage that can be used is whatever virtual 
storage is available up to 8192K bytes. 


All or part of the storage required is obtained from user 
storage. If the access methods are made resident at IPL time, 
they are allocated in system storage. However, 6K bytes is 
always reserved for system use. 


The loader code could also be made resident in the link pack 

area. If so, it requires the following space: HEWLDRGO, the 
control/interface module Calias LOADER), approximately 700 
bytes; HEWLOADR, the loader processing portion, approximately 
13 664% bytes. 


The size of the loaded program is the same as if the program had 
been processed by the linkage editor and program fetch. 


The loader does not use auxiliary storage space for work areas. 
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Virtual Storage 
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(in Bytes) 





Comments 


Concatenation of 
different BLKSIZE and 
BUFNO must be 


Consideration 


Object Module Buffers 
and DECBs 


Load Module Buffer and 
DECBs 
SYSTERM DCB Buffers and Allocated if TERM 
| DECBs option is specified 


SYSLOUT Buffers and BUFNOXCBLKSIZE + 24) Buffer size rounded up | 
DECBs to integral number of 
double words. (Minimum 
BUFNO=2) 


Size of program being Program size Program size is 
loaded restricted only by 
available virtual 
| storage, up to 8 
megabytes 


a | Each external relocation 
( dictionary entry 
Largest ESD number Gn Cn is the largest Allocated in 
number of ESDs in any eee of 32 
input module) entries 
Fixed Loader Table Size Subtract 88 if NOPRINT 
is specified 


Condensed Symbol Table l2n (n is the total Built only if TSO is 
number of control operating and space is | 


BSAM 
BUFNOXCBLKSIZE + 24) 





considered. (Minimum 
BUFNO=2) 











sections and common available 
areas in the loaded 
program) 





Figure 77. Virtual Storage Requirements 
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The return code of a loader step is determined by the return 


codes resulting from loader processing and from loaded program 


processing. 


The return code indicates whether errors occurred during the 
execution of the loader or of the loaded program. The return 
code can be tested through the COND parameter of the JOB 

statement specified for this job and/or the COND parameter of 


the EXEC statement specified in any succeeding job step. 
details, see the publication JCL). 


codes. 


Code Loader 
Returned Return 
to Caller Code 


Conclusion or Meaning 


Program loaded successfully, 
and execution of the loaded 
program was successful. 


The loader found a condition 
that may cause an error during 
execution, but no error 
occurred during execution of 
the loaded program. 


The loader found a condition 
that may cause an error during 
execution, but no error 
occurred during execution of 
the loaded program. 


Program loaded successfully, 
and an error occurred during 
execution of the loaded 
program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


Program loaded successfully, 
and an error occurred during 
execution of the loaded 
program. 





Figure 78 (Part 1 of 2). Return Codes 


1 Error diagnostics CSYSOUT and/or SYSTERM data set) for the 


loader will show the severity of errors found by the loader. 
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Figure 78 shows the return 




















Code 


Returned 
to Caller 





Conclusion or Meaning 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 















8CLET) The loader found a condition 
that may cause an error during 
execution, and an error did 

occur during execution of the 


loaded program. 


The loader found a condition 
that could make execution 
impossible. The loaded 
program was not executed. 


Program loaded successfully, 
and an error occurred during 
execution of the loaded 
program. 


The loade’ found a condition 
that may cause an error during | 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader found a condition 
that may cause an error during 
execution, and an error did 
occur during execution of the 
loaded program. 


The loader could not load the 
program successfully; 
execution impossible. 


8CLET) 


~ 
NO 


~~ 
oN 


Program loaded successfully, 
and the loaded program found a 
terminating error. 


p= 
ON 


The loader found a condition 
that may cause an error during 
execution, and a terminating 


error was found during 
execution of the loaded 
program. 








The loader found a condition 
that may cause an error during 
execution, and a terminating 
error was found during 
execution of the loaded 
program. 


The loader could not load 
| program; execution impossible. 


Figure 78 (Part 2 of 2). Return Codes 


8C LET) 







put 
ON 
p= 


| bh 
RO 
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This glossary includes definitions 
developed by the American National 
Standards Institute (ANSI). This 
material is reproduced from the American 


» copyright 1977 by the 
Computer and Business Equipment 
Manufacturers Association, copies of 
which may be purchased from the American 
National Standards Institute, 1430 
Broadway, New York, New York 10018. 
ANSI definitions are preceded by an 
asterisk(X). 


xaddress. An identification, as 
represented by a name, label, or number, 
for a register, location in storage, or 
any other data source or destination 
such as the location of a station ina 
communication network; any part of an 
instruction that specifies the location 
of an operand for the instruction. 


address constant. <A value, or an 


expression representing a value, used in. 


the calculation of storage addresses} 
aa be used for branching or retrieving 
ata. 


addressing mode (AMODE). The attribute 
of an entry point in which control is 
received. 


address translation. The process of 
changing the address of a data item or 
an instruction from its virtual address 
to the real storage address of the 
location where it will reside. See also 
dynamic address translation. 


alias name. An alternate name or entry 
point for a load module that is also 
entered in the output module library 
directory entry along with the member 
name. 


automatic call library mechanism. The 
process whereby control sections are 
processed by the linkage editor or 
loader to resolve external references to 
members of partitioned data sets not 
resolved by primary input processing. 


auxiliary storage. Data storage other 
than virtual storage; for example, 
storage on magnetic tape or 
direct-access devices. 


common area. A control section used to 
reserve a virtual storage area that can 
be referred to by other modules; may be 
either named or unnamed (blank). 


common segment. A segment upon which 
two exclusive segments are dependent. 


composite external symbol dictionary 
(CESD). Control information associated 


with a load module that identifies the 
external symbols in the module. 


control section. That part of a program 
Cinstructions and data) specified by the 


programmer to be a relocatable unit, all 


elements of which are to be loaded into 
adjoining storage locations for 
execution. Abbreviated CSECT. 


control section name. 
of a control section. 


The symbolic name 


demand paging. Transfer of a page from 
external page storage to eek storage at 
the time it is needed for execution. 


downward reference. A reference made 
from a segment to another segment lower 
in the same path; that is, farther from 
the root segment. 


dynamic address translation (DAT). (1) 
The change of a virtual storage address 
to a real storage address during 
execution of an instruction. See also 
address translation. (2) A hardware 
feature that performs the translation. 


entry name. A name within a control 
section that defines an entry point, and 
can be referred to for execution by any 
control section. 


exclusive reference. A reference 
between exclusive segments; that is, a 
reference from a segment in storage to 
an external symbol in a segment that 
will cause overlay of the calling 
segment. 


exclusive segments. Segments in the 
same region of an overlay program, 
neither of which is in the path of the 
other; they cannot be in virtual storage 
simultaneously. 


external name. A name that can be 
referred to by any control section or 
separately assembled or compiled module; 
that is, a control section name or an 
entry name. 


external page storage. The portion of 
auxiliary storage that is used to 
contain pages. 


external reference. (1) A reference to 
a symbol that is defined as an external 
name in another module. (2) An external 
symbol that is defined in another 
module; that which is defined in the 
Assembler language by an EXTRN statement 
or by a V-type address constant, and is 
resolved during linkage editing. See 
also weak external reference. 
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external symbol. A control section 
name, entry point name, or external 
reference that is defined or referred to 
in a particular module. A symbol 
contained in the external symbol 
dictionary. 


external symbol dictionary (ESD). 
Control information associated with an 
object or load module that identifies 
the external symbols in the module. 


inclusive reference. A reference 
between inclusive segments; that is, a 
reference from a segment in storage to 
an external symbol in a segment that 
will not cause overlay of the calling 
segment. 


inclusive segments. Segments in the 
same region of an overlay program that 
are in the same path; they can be in 
virtual storage simultaneously. 


invalid exclusive reference. An 
exclusive reference in which a common 
segment does not contain a reference to 
the symbol used in the exclusive 
reference. 


library. In this publication, a 
partitioned data set that always 
contains named members. 


load module. The output of the linkage 
editor; a program ina format suitable 
for loading into virtual storage for 
execution. 


load module buffer. An entity of 
virtual storage used by the linkage. 
editor to read input load module text 
records and possibly to retain the text 
information in storage for subsequent 
writing of the output load module text 
records. 


xmodule. A program unit that is 
discrete and identifiable with respect 
to compiling, combining with other 
units, and loading, for example, the 
input to, or output from, an assembler, 
compiler, linkage editor, or executive 
routine. 


multiple load module processing. A 
method of processing whereby two or more 
load modules can be produced ina single 
linkage editor job step. 


xobject module. A module that is the 
output of an assembler or compiler and 
is input to a linkage editor. 


overlay program. A program in which 
certain control sections can use the 
same storage locations at different 
times during execution. 


xoverlay supervisor. A routine that 
controls the proper sequencing and 
positioning of segments of computer 
programs in limited storage during their 
execution. 
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overlay tree. A graphic representation 
showing the relationships of segments of 
an overlay program and how the segments 
are arranged to use the same main 
storage area at different times. 


page. (1) A fixed-length block of 
instructions, data, or both, that can be 
transferred between real storage and 
external page storage. (2) To transfer 
instructions, data, or both between real 
storage and external page storage. 


page fault. A program interruption that 
occurs when a page that is marked "not 
in real storage" is referred to by an 
active page. 


paging. The process of transferring 
pages between real storage and external 
page storage. 


path. All of the segments in an overlay 
tree between a given segment and the 
root segment, inclusive. 

private code. An unnamed control 
section. 


program. A logically self-contained 
sequence of operations or instructions 
that, when followed in some 
predetermined sequence, will produce a 
specified result; a sequence of 
instructions to be performed by a 
computer; one or more modules, in source 
language or relocatable object code, or 
one module in executable code, that is a 
logically self-contained process. 


program fetch. A program that prepares 
load modules for execution by loading 
them at specific storage locations; it 
also readjusts each address constant. 


pseudoregister. In PL/I, a location in 
virtual storage that is used as a 
pointer to dynamically acquired virtual 
storage. It enables the PL/I compiler 
to generate reenterable code. External 
dummy sections give the programmer using 
Assembler F or Assembler H the same 
facility. 


real storage. The storage from which 
the central processing unit can directly 
obtain instructions and data, and to 
which it can directly return results. 


reenterable load module. A module that 
can be used concurrently by more than 
one task. 


refreshable load madule. A load module 
that cannot be modified by itself or by 
any other module during execution; can 
be replaced by a new copy during 
execution by a recovery management 
routine without changing either the 
sequence or results of processing. 


region. In an overlay structure, a 
contiguous area of virtual storage 
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within which segments can be loaded 
independently of paths in other regions. 
Only one path within a region can be in 
virtual storage at any one time. 


relocation. The modification of address 
constants required to compensate for a 
change of origin of a module, program, 
or control section. 


RSECT. A read-only CSECT in the 
nucleus. 


root segment. That segment of an 
overlay program that remains in virtual 
storage at all times during the 
execution of the overlay program; the 
first segment in an overlay program. 


residence mode (RMODE). Defines whether 
the program must be resident in storage 
addressable by 24-bit addressing or 3l- 
bit addressing. 


scatter format. A load module attribute 
that permits the control program to 
dynamically load control sections into 
noncontiguous areas of virtual storage. 


segment. The smallest functional unit 
Cone or more control sections) that can 
be loaded as one logical entity during 
execution of an overlay program. 


serially reusable load module. A module 
that cannot be used by a second task 
te the first task has finished using 
i 





source module. The source statements 
that constitute the input to a language 
translator for a particular translation. 


storage block. A 2K-byte block of real 
storage to which a storage Key can be 
assigned, processor-model dependent. 


upward reference. A reference made from 
a segment to another segment higher in 
the same path; that is, closer to the 
root segment. 


valid exclusive reference. An exclusive 
reference in which a common segment 
contains a reference to the symbol used 
in the exclusive reference. 


virtual address. An address that refers 
to virtual storage and must, therefore, 
be translated into a real storage 
address when it is used. 


virtual storage. Addressable space that 
appears to the user as real storage, 
from which instructions and data are 
mapped into real storage locations. The 
size of virtual storage is limited by 
the addressing scheme of the computing 
system and the amount of auxiliary 
storage available, rather than by the 
actual number of real storage locations. 


weak external reference. An external 
reference that does not have to be 
resolved during linkage editing. If it 
is not resolved, it appears as though 
its value was resolved to zero. 
Abbreviated WXTRN. , | 
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replacing control sections 88, 96 
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See address constant 
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additional input sources 
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processing of 27-35 
specification of 
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of main entry point 
module map 117 
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resolution of 6-9 
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assignment 
linkage editor 19 
loader | 
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loader 124 
residence mode 41 
control section name 7 
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entry point 111 
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override 19 
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loader: 9 
Private code 7 
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example 109 
linkage editor 36 
loader 
specifying 109 
ALIAS statement 68, 109 
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asynchronous overlay supervisor 185 
attributes, module 

See module attributes 
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Authorized Program Facility CAPF) 18 
automatic call library for loader 

DD statement for 132 

description of 122 

options 
automatic call library mechanism 117 


See also call library, linkage editor 


module map 
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examples 96-98 
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note on overlay programs 96 
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using REPLACE statement 102 
changing external symbols 94 
class test table 172 
collection of common areas 111, 182-184 
common area 
blank 7 
collection of lll, 182, 184 
definition 
lengthening 18, 72 
module map 116 
named 
ordering named 102-103 
reserving storage for 11] 
common segment 
definition 170 
exclusive references 170 
promotion of common areas 182 
comparison of linkage editor and 
loader l, 
compatibility, linkage editor and 
loader 127 
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function 
object and load modules 6 
storage required 161 
using IDENTIFY statement 73 


[> | 


data definition statement 
See DD statement 
data for loaded program 135 
data set 
concatenation of 29, 34, 133-135 
linkage editor 
input 
output 107 
loader 133 
DCB information 
linkage editor 54 
loader 132 
DCBS option, block size 49 
DD statement 
general description 54 
linkage editor data sets 
ddnames 54-56 
SYSLIB 30, 56 
SYSLIN 55 
SYSLMOD 57 
SYSPRINT 57 
SYSTERM 59 
SYSUT1 56 
loader data sets 
ddnames 132, 138 
SYSLIB 134 
SYSLIN 133 
SYSLOUT 134 
SYSTERM 134 
ddname list 105 
ddnames, linkage editor 
invoking 54-59 
loader 
automatic call library 132 
diagnostic data set 
input data set 133 | 
specifying alternate names 105, 
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default module attributes 42 
deleting a control section 100 
deleting an entry name 100 
deleting modules 122 
diagnostic messages 
linkage editor 
directory 115 
format 113-115 


loader 
defined by SYSLOUT DD and SYSTERM 
DD 143 
format 143 


diagnostic output 
linkage editor 
messages 113 
optional 116-118 
options, summary 17-18 
loader 
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data set 134 


format 143 
options 129 
dictionaries 


composite external symbol 10, 161 

external symbol 

relocation 6, 9, 160 
directory entry 

authorization code lll 

changing 95 
disposition messages 113-114 
downward call 

See downward reference 
downward reference 

definition 163 

maximum number 162 





editing 

conventions 92-93 

module 92-93 
end of module indication 9 
END statement 

object module 6 

specifying entry point 110 
ENTAB Centry table) 173 
entry address, module map 117 
entry name 

definition 7 

ESD 


changing 94 
deleting 100 
module map 116 
entry point 
example 110 
loaded program 130, 140 
specification of 
END statement 110 
ENTRY statement 71, 110 
ENTRY statement 
main entry point 110 
summary 
entry table 173 
EOM Cend of module indication) 9 
EP loader option 130 
error conditions 
See severity code 
error messages 
See diagnostic messages 
ESD Cexternal symbol dictionary) 7 
exclusive call option 
exclusive reference 
definition 169 
entry table 173 
restrictions 170 
segment table 173 
XCAL option 42 
exclusive segments 
note on overlay programs 96 
EXEC statement 
linkage editor 
introduction 36 
job step options 36 
program name 36 
REGION parameter 53 
return code 53 
loader 
description 128, 132 
examples 
executable module 42 


EXPAND statement 18, 72 
external dummy section 7, 16, 112 

See also pseudoregister 

definition 7 

processing of 16, 112 
external name 

See also control section name, entry 

name 

definition 5 
external reference 

changing 94 

definition 5, 7 | 

external symbol dictionary 7 

resolving 12, 27 

weak 

automatic library-call 27 
cross-reference table 118 

external symbol 

changing 94 

definition 5 
external symbol dictionary 7 


functions 
linkage editor 13 
loader 122 

HEWL 36, 61 


HEWLOAD 1539, 142 
HEWLOADR 139 
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roe statement summary 73 
R 
See CSECT identification records 
IEBUPDTE program 
input statements 156 
INCLUDE statement 
requesting additional data sets as 
input 32 
specifying ddname of DD statement 32 
summary 75 
included data sets 
concatenated data sets 33 
library members 34 
linkage editor 32 
sequential data sets 33 
inclusive reference 
when to use 170 
inclusive segments 
definition 169 
incompatible job step options 51 
incompatible module attributes 42 
input data sets 
linkage editor 22 
loader 133 
input processing 22 
input sources 
linkage editor 9 
loader 128, 133 
INSERT statement 
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summary 76 
using 180 
intermediate data set 
devices supported 162 
linkage editor 
loader 127 
SIZE option 43, 160. 
storage required 160 
SYSUT1 DD statement 56 
intermediate text records, number 
produced 16] 
internal data area 127 
invalid attributes or options 113 
invalid exclusive reference 
illustration 
invocation of 
linkage editor 105 
loader 8 


job control language summary 36 
job control statements 
linkage editor 36 
loader processing 
basic format 128 
compile-~load job 135 
load job 
multiple compilations 136 
job step 
options 
EXEC statement 36 


let execute option 43 
LET option 
linkage editor 43, 152 
loader 127, 130 
overlay programs 182 
library call 
See automatic call library for loader 
library members 
including 34 
input te linkage editor 23 
input to loader 3 
LIBRARY statement 
additional call libraries 30 
NCAL option 
never-call function 31 
restricted no-call function 30 


LINK command 21 
LINK macro 
invoking 
linkage editor 105 
loader 139 
link pack area resolution 
loader 131 
linkage editor 
assigning block size 58 
capacities 
cataloged procedures 61 
compared to loader 1, 122 
control statement summary 66 
DD statements 55-59 


functions 13 
input 
additional data sets 22 
control statements 26 
object modules 26 
primary data sets 22 
invoking 
output 107 
processing 9 
relationship to operating system 2] 
storage requirements 
when to use 
LINKEDIT 36 
linking modules’ 14 
LIST option 50, 116 
LKED procedure 61-63 
LKEDG procedure 63-64 
LOAD macro 
invoking the loader 141 
only loadable modules 38 
load module 
attribute assignment 17 
attributes 37 
buffer 44 
definition 4 
entry point 110 


input 
linkage editor 22 
loader 128 


linkage editor output 107 
multiple processing of 112 
structure 6 
load module buffer 
allocating storage 4%4 
load module creation 10 
load module format 
loader 
example 
load point 168, 176 
load step 1, 128 
loaded program 
data 135 
module map 143 
options 129, 132 
return codes 192 
loader 
abnormal termination message 
CVS2) 143 
alias name 138 
compared to linkage editor 1, 122 
compatibility with linkage 
editor 
data sets 133 
input 122, 128 
invoking 138 
options 129, 132 
output 
program name 138 
restrictions 127 
return codes 192 
when to use l 
LOADGO command 127 
loading 
with identification 142 
without identification 140 
logical record length 
linkage editor data sets 
blocking factors 55 
diagnostic output 57 
input 55 
SIZE option 43 
LRECL operand (DCB macro) 54-55 
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macros, linkage editor NAME loader option 130 





format 105 NAME statement 
MAP option multiple load module processing 112 
linkage editor 50, 116-117 replace function 
loader 127, 130 summary 
maximum record size for device SYSLMOD DD 108 
types 44-45 named common area 
member name aligning on page boundary 103 
definition 108 collection of lll, 182 
example 108 definition 7 
specifying 108 module map 116 
member, partitioned data set NCAL option 
including 34 linkage editor 3l, 43 
input to the linkage editor 23 loader 127, 1 
input to the loader 133 NE attribute 38 
messages negation of automatic library call 
disposition 113-114 linkage editor 
examples 115 loader 
format 114 diagnostic output 131 
text 115 module map 131 
unnumbered 114 search of link pack area 131 
MODE statement not editable attribute 38 
example 80 not executable attribute 43 
specifying addressing mode 79 reenterable attribute 39 
specifying residence mode 79 refreshable attribute 40 
summary 79-80 serially reusable 39 
values 80 never-call function 
modular programming 4 cross-reference table 118 
module attributes specifying external references 31 
default attributes 42 no automatic library call option 43 
describing output module 37 no-call 
en incompatible attributes 42, 51 NOCALL loader option. 129 
not editable 38 node point 
not-executable 42 See load point 
only loadable 38 NOLET loader option 1530 
overlay 38 NOMAP loader option 130 
refreshable 40 NOPRINT loader option 131 
reusability NORES loader option 131 
reenterable 39 not editable attribute 
serially reusable 39 linkage editor 38 
scatter format 37 loader 127 
test 40 not-executable attribute 42 
module disposition messages 113 NOTERM loader option 132 


module editing 
general description 92 


summary 14 | : 

module linking 14-15 

module map , 
linkage editor 


description 116-117 object module 
example 117 definition 4 
MAP option 50 input to linkage editor 26 
loader input to loader 
description 143 structure 6 
example 144 virtual storage 127 
specifying 130 OL attribute 
module, definition 4 only loadable attribute 38 
multiple load module processing optional output 116 
producing 112 options, incompatible 5] 
multiple region overlay program options, linkage editor 
general description 173 addressing mode 182 
specifying 177 module attributes 37 
using 173 output 


residence mode 182 
space allocation 43 
special processing 42-43 
ORDER statement 82, 102-103 
origin 
control section in module map 116 
region 177 
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segments 168 
output module library 107 
output of linkage editor 
diagnostic messages 113 
load module 107 
optional output 116-118 
output module library 107 
output options 
output of the loader 
messages 143 
module map 143 
| specifying 128-132 
output text record length 160 
overlap of loading and processing, 
overlay segments 
overlay attribute 
specifying 38 
overlay program 
communication 185 
design 163 
module map 116 
multiple region 173 
process 172-173 
region origin 177 
respecifying control statements 176 
sample program 150-156 
segment origin 168, 176 
Single region 
special considerations 182 
specifying 176 
storage requirements 184-185 
OVERLAY statement 
specifying 176-181 
summary 84 
overlay supervisor, definition 172 
overlay tree 
positioning segments 166 
overriding cataloged procedures 
DD statements 65 
EXEC statement 64 
OVLY attribute 38-39 


page boundary 
see cabal control sections or named 
ommon areas 
PAGE retatcnent 
aligning control sections 103 
summary 
parameter 
addressing mode 41 
combination 4] 
residence mode 41 
partitioned data set 
input 
linkage editor 23 
loader 
output, linkage editor 107 
path 
in overlay program 163 
placement of control statements 67 
positioning control sections 178 
preloaded text 127, 143 
primary input data set 
control statements 25 
job control language 
specifications 22 
object modules 22, 26 
PRINT loader option 131 
private call libraries 29 





private code 


definition 7 £o% 


module map 117 a 


procedure LKED 61-63 ae, 


procedure LKEDG 63-64% 
processing history, tracing 
CSECT Identification record 18 
processing options, special 42 
program fetch 
functions 1] 
prompter 
linkage editor, function or 2l 
loader, function of 7 
pseudoregister 
definition 7 
module map 117 | 
processing of 16, li2 


read-only attribute, assignment 2l 
RECFM 
See record format 
record format CRECFM) 
linkage editor data sets 
diagnostic output 59 
input 54-55 
load modules 55-59 
loader data sets 133 
record size 
maximum 
device type 45 
reenterable attribute 39 | 
reenterable load module 
module attribute 39 Si 
REFR attribute 40 
refreshable attribute 40 
refreshable load module 
module attribute 42 
REGION parameter 
specifying storage 53 
region, overlay programs 
specifying 177 
using 173 
region, virtual storage 
linkage editor 
cataloged procedures 6] 
SIZE option 
loader 140 
relocating a load module 4 
relocation dictionary 
number of entries 160 
using 9 
RENT ateri bute 39 
replace function 95-101, 109 
REPLACE statement 
deleting CSECT 101 
example 99 
sample program 1496-150 
summary 88-89 
using 
replacing control sections, assembler 
language note 96 
replacing external symbols 
See CHANGE statement, changing 
external symbols 
replacing load modules with the same P sas 
name (% 


ear fos (oe 
repositioning control statements ee 


automatic call library 181 
INSERT control statement 76, 178 
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reprocessing load modules 
entry point assignment 110 
not editable attribute 38 
RES loader option 131 
reserving storage l11]1 
residence mode 
assignment 
linkage editor 20 
loader 3 
output load module 107 
combinations 
addressing mode 4] 
loader 124 
control section name 7 
default 20 
entry point 111 
implied 124 
options 182 
override 20 
parameter 
linkage editor 41 
loader 
private code 7 
resolving external references 12, 27 
restricted no-call function 
restrictions, virtual storage size 
requirements 40 
return codes 
linkage editor 53 
loader 
severity code 114 
REUS attribute 
reusability attributes 
general description 39 


reenterable 

serially reusable 39 
RLD 

See relocation dictionary 
RMODE 


See residence mode 
root segments 
definition 163 
OVERLAY 176 
segment table 173 
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sample programs 145 
scatter loading 37 
SCTR attribute 37 
SEGLD macro 185 
segment 166, 168, 169, 172 
See also exclusive, inclusive, root 
segments 
communication 169-172 
dependency 
origin 168 
segment load macro 188 
segment table 173 
segment wait macro 
SEGLD 189 
using 188 
SEGTAB (segment table) 173 
SEGWNT macro 
SEGLD 189 
using 188 
sequential data set 
INCLUDE statement 33 
input to linkage editor 22, 33 
input to loader 133 
serially reusable 
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attribute 39 
SETCODE statement 19, 90 
SETSSI statement 91 
severity code 
linkage editor messages 114 
return codes 
severity 0,2 errors 114 
SIZE option 
linkage editor 43, 60 
loader 131, 190 
space allocation 
DCBS option 49 
maximum values 43, 47 
minimum values 43, 47 
SIZE option 43 
specifying storage 43 
Special processing options 
affecting automatic library call 
mechanism 
affecting output module 42 
summary 17 
static external areas 111 
SYSLIB DD statement 
automatic call library 27 
linkage editor 
loader 3 
SYSLIN DD statement 55, 133 
See also automatic call library for 
loader 
linkage editor 55, 133 
SYSLMOD DD statement 57, 112, 113 
See also output module library 
function 
NAME statement 112-113 
referenced by INCLUDE statement 57 
SYSLOUT DD statement 131, 134 
SYSPRINT DD statement 57 
system call library 
example 
list 28 


system status index information, storage 


of 18 
SYSTERM data set 
linkage editor 5l, 59, 115 
loader 133, 134, 143 
SYSTERM DD statement 
linkage editor 51, 59, 115 
loader 133, 134; 143 
SYSUT1 DD statement 56 


TEMPNAME 108 
temporary data set 24, 108 
TERM option 
linkage editor 5l, 59, 115 
loader 132 . 
TEST attribute 40 
text 
message 115 
note 
processing out-of-order 6 
time sharing option 
See TSO 
tracing processing history 18 
TRANSFORM table 172 
tree structure 
positioning of segments 166 
purpose of 5 
TSO Ctime sharing option) 
linkage editor 
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invoking 21 
SYSTERM data set 59 
TERM option 115 
loader 
invoking 127 
SYSTERM data set 132, 134 
TERM option 132 


Lv] 


unnumbered messages 113-114 
unresolved references 
automatic library-call, resolving 
with 
cross-reference table 118 
upward reference, definition 163 
user-specified 
input 9 
storage 17 
user-written library 29 
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V-type address constant 
branch instruction, overlay 187 
CALL 87 
SEGLD 188 
SEGHT 189 
valid exclusive reference 170 





virtual storage requirements 


linkage editor 
loader 190 


overlay programs 184-185 


restrictions 


wait for loading of poorest 188 


warning messages 114-11 
weak external reference 


automatic library-call 


cross-reference table 
definition 


118 


level F linkage editor 
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XCAL option 42, 182 
XCTL macro 
input to loader 127 
invoking the loader 
XREF option 50 
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